| … | … | @@ -0,0 +1,268 @@ |
| 1 | # From godot-keet to hyper-social — Evolutionary Roadmap |
| 2 | |
| 3 | ## The Gap |
| 4 | |
| 5 | **godot-keet** is a production P2P chat client (Godot 4.6 + keet-daemon over UDS). It works: rooms, chat, groups, files, identity, discovery, OTA updates. Single-platform — Keet only. |
| 6 | |
| 7 | **hyper-social** is a multi-platform social ecosystem (12 projects, 363 tests, all passing): 5 bridges (IRC live on Libera), 3 panels (wiki, board, feed), 1 automation runtime, 1 orchestration hub. |
| 8 | |
| 9 | The path is evolutionary — extend what works rather than rewrite. |
| 10 | |
| 11 | ## Key Architectural Insight |
| 12 | |
| 13 | **Bridges are invisible to the Godot client.** When bridge-irc relays an IRC message into a Keet room, godot-keet already displays it — it's just a regular room message from the bridge bot. The first phases require ZERO Godot changes. |
| 14 | |
| 15 | ## The Architecture |
| 16 | |
| 17 | godot-keet's `index.js` launcher starts keet-daemon in-process, then launches Godot. The evolution: replace keet-daemon with hyper-social Hub, which starts keet-daemon internally AND manages bridges, panels, and services. |
| 18 | |
| 19 | ``` |
| 20 | CURRENT: EVOLVED: |
| 21 | godot-keet launcher godot-keet launcher |
| 22 | ├── keet-daemon (in-process) ├── hyper-social Hub (in-process) |
| 23 | └── Godot binary │ ├── keet-daemon (managed service) |
| 24 | │ ├── bridge-irc (managed service) |
| 25 | │ ├── bridge-discord (managed service) |
| 26 | │ ├── hyper-feed (managed service) |
| 27 | │ ├── hyper-wiki (managed service) |
| 28 | │ └── hyper-board (managed service) |
| 29 | └── Godot binary |
| 30 | ``` |
| 31 | |
| 32 | The Hub exposes the same UDS socket with the same protocol. Existing keet-daemon routes pass through unchanged. New `hub.*`, `bridge.*`, `feed.*`, `wiki.*`, `board.*` routes are added. godot-keet's GDScript code sees a superset of the API it already uses. |
| 33 | |
| 34 | ### Why This Works |
| 35 | |
| 36 | 1. **Zero breaking changes** — every existing keet-daemon route continues to work |
| 37 | 2. **Single process** — no multi-service coordination nightmare |
| 38 | 3. **Single socket** — Godot still talks to one UDS endpoint |
| 39 | 4. **Incremental adoption** — each phase adds routes and UI independently |
| 40 | 5. **Fracture principle honored** — each hyper-social project remains an independent npm module, just orchestrated by the Hub |
| 41 | |
| 42 | ## Phases |
| 43 | |
| 44 | ### Phase 0: Bridges Run Alongside (No Code Changes) |
| 45 | |
| 46 | Deploy bridges as separate processes alongside keet-daemon. bridge-irc already runs on Libera. Start it in a tmux window connecting to the same keet-daemon UDS socket. |
| 47 | |
| 48 | **Result**: IRC messages appear in Keet rooms. godot-keet shows them with no changes. |
| 49 | |
| 50 | This is free. It proves the concept immediately. |
| 51 | |
| 52 | ### Phase 1: Hub Wraps keet-daemon |
| 53 | |
| 54 | Create `hub-daemon` package that imports keet-daemon + Hub, exposes unified UDS API. |
| 55 | |
| 56 | **New files**: |
| 57 | - `hyper-social/hub-daemon/index.js` — entry point (replaces `startDaemon()`) |
| 58 | - `hyper-social/hub-daemon/lib/hub-router.js` — extends keet-daemon router |
| 59 | |
| 60 | **New routes**: |
| 61 | ``` |
| 62 | hub.status → service list, bus stats, started state |
| 63 | hub.graph → rooms with their linked services |
| 64 | hub.services → list all managed services |
| 65 | hub.service.start → start a service by ID |
| 66 | hub.service.stop → stop a service by ID |
| 67 | bridge.list → list active bridges with status |
| 68 | bridge.configure → configure bridge (platform, channel, room, credentials) |
| 69 | ``` |
| 70 | |
| 71 | **Key constraint**: ALL existing keet-daemon routes (`rooms`, `send`, `subscribe`, `discovery.*`, etc.) work unchanged. The Hub is a superset. |
| 72 | |
| 73 | **Result**: godot-keet switches from `startDaemon()` to `startHub()` with zero GDScript changes. |
| 74 | |
| 75 | ### Phase 2: Bridge Awareness in Godot |
| 76 | |
| 77 | Detect bridged messages, show platform origin, display bridge status. |
| 78 | |
| 79 | **New files**: |
| 80 | - `godot-keet/addons/keet_social/keet_bridge.gd` — bridge API manager |
| 81 | |
| 82 | **Modified files**: |
| 83 | - `godot-keet/scripts/ChatPanel.gd` — platform badge rendering |
| 84 | |
| 85 | **How it works**: |
| 86 | - Messages from bridges have a prefix pattern: `[IRC] nick:` or envelope metadata |
| 87 | - `keet_bridge.gd` calls `bridge.list` to get active bridges per room |
| 88 | - Chat panel renders platform icon next to bridged messages |
| 89 | - Room settings shows which bridges are active |
| 90 | |
| 91 | **Result**: Users see "[IRC] alice: hello" with an IRC icon instead of plain text. |
| 92 | |
| 93 | ### Phase 3: Bridge Management UI |
| 94 | |
| 95 | Configure, start/stop bridges from within godot-keet. |
| 96 | |
| 97 | **New files**: |
| 98 | - `godot-keet/scripts/BridgeSettingsWindow.gd` — bridge configuration panel |
| 99 | |
| 100 | **Features**: |
| 101 | - List active bridges with status indicators (running/stopped/error) |
| 102 | - Configure new bridge (platform, channel/server, credentials) |
| 103 | - Start/stop bridges |
| 104 | - Bridge credential management (bridge-vault via hub routes) |
| 105 | |
| 106 | **Result**: Users can bridge an IRC channel to a Keet room from the Godot UI. |
| 107 | |
| 108 | ### Phase 4: Feed Panel |
| 109 | |
| 110 | Aggregated timeline across all rooms and platforms. |
| 111 | |
| 112 | **New files**: |
| 113 | - `godot-keet/scripts/FeedPanel.gd` — timeline scene |
| 114 | |
| 115 | **Extended files**: |
| 116 | - `godot-keet/addons/keet_social/keet_feed.gd` — already exists (experimental) |
| 117 | |
| 118 | **New hub routes**: |
| 119 | ``` |
| 120 | feed.timeline → aggregated messages across rooms, sorted by time |
| 121 | feed.filter → filter by platform, room, author, type |
| 122 | feed.subscribe → real-time feed updates (push events) |
| 123 | ``` |
| 124 | |
| 125 | **UI**: "Feed" button in toolbar. Chronological stream across all rooms. Filter chips for platform and room. Click message → jump to room chat view. |
| 126 | |
| 127 | **Result**: Single view of all activity across all platforms. |
| 128 | |
| 129 | ### Phase 5: Panel Integration (Wiki + Board) |
| 130 | |
| 131 | Wiki and kanban board attached to rooms. |
| 132 | |
| 133 | **New files**: |
| 134 | - `godot-keet/scripts/WikiPanel.gd` |
| 135 | - `godot-keet/scripts/BoardPanel.gd` |
| 136 | |
| 137 | **New hub routes**: |
| 138 | ``` |
| 139 | wiki.pages → list pages for room |
| 140 | wiki.get → get page content (markdown) |
| 141 | wiki.put → create/update page |
| 142 | wiki.search → full-text search |
| 143 | board.cards → list cards for room |
| 144 | board.create → create card (title, description, assignee, labels) |
| 145 | board.move → move card between lanes (todo/progress/done) |
| 146 | board.update → update card details |
| 147 | ``` |
| 148 | |
| 149 | **UI**: Room toolbar gets "Wiki" and "Board" buttons. Clicking switches the main content area. Rooms opt in via settings. |
| 150 | |
| 151 | **Result**: Rooms become workspaces — chat + wiki + kanban in one place. |
| 152 | |
| 153 | ### Phase 6: Cross-Platform Identity |
| 154 | |
| 155 | Link identities across platforms. |
| 156 | |
| 157 | **New files**: |
| 158 | - `godot-keet/addons/keet_social/keet_identity_graph.gd` |
| 159 | |
| 160 | **New hub routes** (wrapping existing `IdentityGraph`): |
| 161 | ``` |
| 162 | identity.link → link two platform identities as same person |
| 163 | identity.resolve → find someone on another platform |
| 164 | identity.linked → get all identities for an alias |
| 165 | identity.aliases → list all known cross-platform people |
| 166 | ``` |
| 167 | |
| 168 | **UI**: Member panel shows platform badges. Click member → see linked identities. Opt-in only — users choose to link. |
| 169 | |
| 170 | **Result**: "alice" recognized as one person across IRC, Discord, and Keet. |
| 171 | |
| 172 | ### Phase 7: Social Graph Navigation |
| 173 | |
| 174 | The MI/MST/clustering pipeline + graph view from [SOCIAL-GRAPH-NAVIGATION.md](SOCIAL-GRAPH-NAVIGATION.md). |
| 175 | |
| 176 | **New files**: |
| 177 | - `godot-keet/scripts/GraphView.gd` — 2D force-directed scene |
| 178 | - `godot-keet/addons/keet_social/keet_graph.gd` — graph data manager |
| 179 | |
| 180 | **New hub routes**: |
| 181 | ``` |
| 182 | graph.compute → trigger MI computation from local membership data |
| 183 | graph.clusters → get detected room clusters |
| 184 | graph.bridges → get rooms that bridge clusters |
| 185 | graph.neighbors → get rooms with highest MI to a given room |
| 186 | graph.sidebar → compute dynamic sidebar ordering for current position |
| 187 | ``` |
| 188 | |
| 189 | **Implementation**: |
| 190 | - MI computation runs in the Hub (JavaScript, same math as `opencog-kb/language-learning/mvp/compute-mi.scm`) |
| 191 | - Godot renders force-directed graph (Node2D + physics springs) |
| 192 | - Click node → enter room → sidebar updates (local section of the sheaf) |
| 193 | - Toggle between graph view and traditional GroupBar + RoomList |
| 194 | |
| 195 | **Result**: Navigate the social graph visually. See community structure emerge from membership data. |
| 196 | |
| 197 | ### Phase 8: Community Emergence Tooling |
| 198 | |
| 199 | The long-horizon vision from [COMMUNITY-EMERGENCE.md](COMMUNITY-EMERGENCE.md). |
| 200 | |
| 201 | **Scope TBD based on what emerges from Phases 0-7:** |
| 202 | - Moderation as subscribable service (labels, not enforcement) |
| 203 | - Deliberation tools (Polis-style consensus-finding) |
| 204 | - Economic tools (mutual aid pooling) |
| 205 | - Community detection + naming (nucleation support) |
| 206 | |
| 207 | ## Migration Strategy |
| 208 | |
| 209 | Each phase is independently deployable and backward compatible: |
| 210 | |
| 211 | | Phase | Godot Changes | Hub Changes | Prerequisite | |
| 212 | |-------|--------------|-------------|--------------| |
| 213 | | 0 | None | None | bridge-irc deployed | |
| 214 | | 1 | 1 line in index.js | New hub-daemon package | None | |
| 215 | | 2 | New keet_bridge.gd + chat badges | Uses Phase 1 routes | Phase 1 | |
| 216 | | 3 | New BridgeSettingsWindow.gd | Uses Phase 1 routes | Phase 1 | |
| 217 | | 4 | New FeedPanel.gd | New feed.* routes | Phase 1 | |
| 218 | | 5 | New WikiPanel.gd + BoardPanel.gd | New wiki.* + board.* routes | Phase 1 | |
| 219 | | 6 | New keet_identity_graph.gd | New identity.* routes | Phase 1 | |
| 220 | | 7 | New GraphView.gd | New graph.* routes + MI engine | Phase 1 | |
| 221 | | 8 | TBD | TBD | Phases 1-7 | |
| 222 | |
| 223 | Phases 2-7 can be done in any order. Phase 1 is the only hard prerequisite (besides Phase 0 which is just deployment). |
| 224 | |
| 225 | ## What Already Exists (Reuse, Don't Rebuild) |
| 226 | |
| 227 | | Component | Location | Status | Reuse In | |
| 228 | |-----------|----------|--------|----------| |
| 229 | | Hub orchestrator | `hyper-social/hyper-social/lib/hub.js` | 74 tests pass | Phase 1 | |
| 230 | | ServiceRegistry | `hyper-social/hyper-social/lib/service-registry.js` | Working | Phase 1 | |
| 231 | | MessageBus | `hyper-social/hyper-social/lib/message-bus.js` | Working | Phase 1 | |
| 232 | | RoomMap | `hyper-social/hyper-social/lib/room-map.js` | Working | Phase 1 | |
| 233 | | IdentityGraph | `hyper-social/hyper-social/lib/identity-graph.js` | Working | Phase 6 | |
| 234 | | bridge-irc | `hyper-social/bridge-irc/` | 26 tests, live on Libera | Phase 0 | |
| 235 | | bridge-discord | `hyper-social/bridge-discord/` | 19 tests pass | Phase 3 | |
| 236 | | bridge-matrix | `hyper-social/bridge-matrix/` | 35 tests pass | Phase 3 | |
| 237 | | bridge-mastodon | `hyper-social/bridge-mastodon/` | 27 tests pass | Phase 3 | |
| 238 | | bridge-email | `hyper-social/bridge-email/` | 23 tests pass | Phase 3 | |
| 239 | | bridge-envelope | `hyper-social/bridge-envelope/` | 21 tests pass | Phase 1 | |
| 240 | | bridge-vault | `hyper-social/bridge-vault/` | 15 tests pass | Phase 3 | |
| 241 | | hyper-feed | `hyper-social/hyper-feed/` | 30 tests pass | Phase 4 | |
| 242 | | hyper-wiki | `hyper-social/hyper-wiki/` | 15 tests pass | Phase 5 | |
| 243 | | hyper-board | `hyper-social/hyper-board/` | 19 tests pass | Phase 5 | |
| 244 | | hyper-daemon | `hyper-social/hyper-daemon/` | 59 tests pass | Phase 8 | |
| 245 | | keet-daemon | `hyper-fleeky/packages/keet-daemon/` | Production | Phase 1 | |
| 246 | | UDS transport | `keet-daemon/lib/uds-transport.js` | Production | Phase 1 | |
| 247 | | Router | `keet-daemon/lib/router.js` | 90 methods | Phase 1 | |
| 248 | | Discovery | `keet-daemon/lib/room-discovery.js` | Production | All phases | |
| 249 | | MI computation | `opencog-kb/language-learning/mvp/compute-mi.scm` | Working | Phase 7 | |
| 250 | |
| 251 | **363 tests already pass across the ecosystem.** The code exists. The path is integration, not creation. |
| 252 | |
| 253 | ## Verification Checklist |
| 254 | |
| 255 | - [ ] Phase 0: bridge-irc messages appear in godot-keet room |
| 256 | - [ ] Phase 1: `hub.status` returns service list via UDS, all existing routes work |
| 257 | - [ ] Phase 2: IRC messages show platform badge in chat |
| 258 | - [ ] Phase 3: start/stop IRC bridge from Godot UI |
| 259 | - [ ] Phase 4: feed timeline shows messages from multiple rooms |
| 260 | - [ ] Phase 5: create wiki page from room, view kanban board |
| 261 | - [ ] Phase 6: link IRC identity to Keet identity, see unified profile |
| 262 | - [ ] Phase 7: graph view shows room clusters, click node → enter room |
| 263 | |
| 264 | ## The Principle |
| 265 | |
| 266 | godot-keet doesn't become hyper-social by being rewritten. It becomes hyper-social by the Hub absorbing keet-daemon, bridges connecting platforms, panels adding capabilities, and the graph navigation surfacing the structure that was always there. |
| 267 | |
| 268 | The community already exists. The rooms already exist. The people already exist. The tools just need to see the whole picture. |