coop/docs/nip29-migration-plan.md

# NIP-29 migration plan

`crates/nip29` is complete and reviewed; `docs/nip29-usage.md` is its API contract. This
plan replaces the Concord stack — `crates/concord`, `crates/community` and
`crates/community_ui` — with it, and lays out the UI surfaces the backend was built for.

Every phase ends with the app building and running. The last phase deletes the old crates,
so nothing is removed until the replacement is in place.

## What is being replaced

| Today | Replacement |
| --- | --- |
| `crates/concord` (`cord01`–`cord06`, `state`, `derive`) | deleted — the relay owns identity, membership, roles and history |
| `crates/community` (`CommunityRegistry`, `Community`, `sync`, `cache`, `rekey`, `history`) | `crates/nip29` (`GroupsRegistry`, `Group`) — already built |
| `crates/community_ui` (`CommunityPanel`) | new `crates/nip29_ui` (`GroupPanel`) |
| Sidebar `Communities` tab + two-level community view (channels / admins / members) | one-level `Groups` tab; admins and members move into a details dialog |
| `dialogs/new_community.rs` | `dialogs/new_group.rs` and a new `dialogs/join_group.rs` |
| `panels/browse.rs` stub | a working browse panel over `GroupsRegistry::browse` |
| `settings.recent_communities` (dead, nothing reads it) | removed |

## Capability disposition

| Concord capability | On NIP-29 |
| --- | --- |
| End-to-end encrypted channels | Dropped. NIP-29 groups are relay-readable; `private` only means members-only read. |
| Channels inside a community | Dropped. A group is one timeline; subgroups are the only hierarchy. |
| Roles and control plane | Relay owns them (`39001`, `39003`); the client reads and displays, never derives authority. |
| Rekey, rotation, refounding, dissolution | Dropped with `cord06`; leaving and deleting are relay operations. |
| Invites | `9009` `create-invite` + the `?invite=` suffix on a group `naddr`. |
| Pins | `9010` → relay mirrors `39005`; the backend is ready. |
| Message deletion | `9005`; the local eviction lands in Phase 0. |
| Reactions | Kind `7` rows arrive as ordinary timeline rows; grouping them under the target is a later enhancement. |
| Members list | `39002` when the relay publishes it; may be absent or partial by design. |
| Community list | `10009`, owned entirely by the backend. |
| Multi-relay communities | One relay per group; migration and forks surface through `Group::elsewhere()`. |
| Attachments | Any kind the relay supports; v1 renders media URLs already parsed by `chat::Message`. |

## Rules the implementation keeps

Carried over from the backend review; they apply to every phase.

- New code goes into `crates/nip29` and `crates/nip29_ui`. Never create a `groups` crate.
- Implementation-block style: methods on the type they belong to, `self` first.
- Read model is subscribe → pump → envelope cache → hydrate. Never `fetch_events`.
- Short-lived subscriptions close on EOSE (`SubscribeAutoCloseOptions`), long-lived ones use a
  prefix the pump recognises; dedup events by id before they mutate state.
- I/O runs on `cx.background_spawn`, called from a foreground `cx.spawn` task; tasks are
  stored on the entity so they cancel with it.
- No comments, no docs, no tests inside the crates. `docs/` is the only place for prose.
- No premature optimization: scan the small vectors, don't build index maps.
- No `unwrap`, no `let _ =` on fallible calls; propagate with `?` and surface errors to the UI
  (relay messages verbatim).
- Views read entities; protocol state never lives in a view. A panel re-reads on the event.
- UI follows the existing components (`ui::button`, `ui::input`, `ui::dock`, `ui::message`,
  `ui::markdown`, `theme` tokens). Copy is sentence case; a dialog names its object
  (`Leave "Pizza Lovers"?` with a `Leave` button).
- `Monitor` stays unadopted; the fork watch already works without relay status.

---

## Phase 0 — `9005` deletes reach local state

Today a `9005` stops the relay serving the event, but the envelope cache and the timeline keep
it. Everything else about deletion is done (the write, the `OK false` path).

Files: `crates/nip29/src/protocol.rs`, `crates/nip29/src/group.rs`, `crates/nip29/src/lib.rs`.

1. `TimelineWindow::remove(&mut self, id: EventId)` — drop the reference so a `previous` tag
   never points at a deleted event.
2. `Group::forget(&mut self, id: EventId, cx: &mut Context<Self>)` (crate-private) —
   `messages.retain`, `index.remove`, `window.remove`; when something was removed, emit
   `GroupEvent::Updated` and `cx.notify()`. `hydrate` stays additive, so a later reload cannot
   resurrect the row once its envelope is gone.
3. The registry's ingestion of our accepted delete: in `ensure`'s `GroupEvent::Sent` arm, when
   `event.kind == Kind::Custom(9005)`, take the target from `event.tags.event_ids().next()`,
   delete its envelope (`Kind::ApplicationSpecificData` + `Tag::identifier(target)` +
   `r = key.cache_tag()`) on the background executor, wait for that to finish, then
   `group.forget(target)` and the usual `reload(key, Some(event))`. The deletion must complete
   before the reload reads the envelopes, or the reload would see the target still cached.

Remote deletes (another admin's `9005` arriving live) are out of scope; the standing REQ does
not carry them, and a relay that no longer serves the event cannot be asked for it.

Validation: `cargo clippy -p nip29 --all-targets`, `cargo fmt -p nip29`,
`cargo check -p coop -p coop_web`. Manually: as an admin, delete a message and confirm the row
disappears and stays gone after a restart.

---

## Phase 1 — `crates/nip29_ui`: the group panel

A new crate, modeled on `community_ui`, that renders one `Entity<Group>`.

Files: `crates/nip29_ui/Cargo.toml`, `crates/nip29_ui/src/lib.rs`,
`crates/nip29_ui/src/message.rs`; one line in `crates/chat_ui/src/lib.rs`.

```toml
# Cargo.toml
[dependencies]
nip29 = { path = "../nip29" }
chat = { path = "../chat" }
chat_ui = { path = "../chat_ui" }
state = { path = "../state" }
ui = { path = "../ui" }
theme = { path = "../theme" }
common = { path = "../common" }
person = { path = "../person" }
settings = { path = "../settings" }

gpui.workspace = true
nostr-sdk.workspace = true
anyhow.workspace = true
smallvec.workspace = true
```

Make `chat_ui`'s text helper shared by flipping `mod text;` to `pub mod text;`. It is the only
change to an existing UI crate in this phase.

```rust
pub fn init(group: Entity<Group>, window: &mut Window, cx: &mut App) -> Entity<GroupPanel>;

pub struct GroupPanel {
    id: SharedString,                                     // "group-<cache_tag>"
    focus_handle: FocusHandle,
    group: WeakEntity<Group>,
    list_state: ListState,
    rendered_texts_by_id: BTreeMap<EventId, RenderedText>,
    input: Entity<TextareaState>,
    tasks: SmallVec<[Task<Result<()>>; 4]>,
    _subscriptions: SmallVec<[Subscription; 2]>,
}
```

The panel keeps **no copy of the timeline**. Rows are `group.read(cx).messages()`; the only
local cache is parsed markdown keyed by event id. Deleting a message, a page arriving, or a
live tail all reduce to "the entity changed, re-read it" — no merge, no index.

Rows: `0` welcome, `1` load-older, then the messages.

- Welcome — `WelcomeMessage` with the group avatar; `Welcome to {name}` and
  `This is the start of {name}.`
- Load older — visible when `group.oldest().is_some()`, disabled while
  `group.loading_more()`, click → `GroupsRegistry::global(cx).update(|registry, cx| registry.load_more(&key, cx))`.
- Message — `MessageRow` with avatar, author (`PersonRegistry`), `created_at.to_human_time()`,
  and `chat_ui::text::rendered_text(&message.content, &message.mentions, &persons, true, cx)`
  cached in `rendered_texts_by_id`. Show the author on a run start (same author, gap under a
  few minutes) like `community_ui` does. Render `message.media` as chat does: one image
  full-width, several in a wrapped row.

Events: subscribe to the group and drive everything from it.

| `GroupEvent` | Panel |
| --- | --- |
| `Incoming` / `Updated` | sync `list_state` (`reset(item_count)` when the count changed) and `cx.notify()` |
| `Eose` | `cx.notify()` — `group.loading()` is now false |
| `Refused(reason)` | show the notice |
| `Sent` | ignore; the registry reloads through the same cache path |

Composer, gated exactly on the NIP's flags:

```rust
let metadata = group.metadata();
let supports_text = metadata.is_none_or(|m| m.supports(Kind::ChatMessage));
let writable = metadata.is_none_or(|m| !m.restricted) || matches!(group.membership(), Membership::Member);
let can_send = supports_text && writable;
```

Send mirrors `community_ui::send`: read `input.value()`, clear the textarea, spawn
`group.send_message(&text, vec![], cx)` and turn an `Err` into an
`autohide(false)` notification — that string is the relay's refusal, verbatim. The panel does
not reload anything; `GroupEvent::Sent` already routes the accepted event through the registry.

Notice above the composer (and centered when there are no messages):

| State | Notice | Action |
| --- | --- | --- |
| `group.refused()` | Relay message | none |
| not a member (`Unknown` / `Removed` / `Refused { reason }`) | `Request to join`, preceded by the refusal reason when there is one | `registry.join_key(key, None, cx)` |
| any of the above while `metadata.closed` | `This group is closed; an invite link is required.` | disabled |
| `Membership::Pending { .. }` | `Waiting for the relay to approve.` | disabled |
| `!supports_text` | `This group doesn't support text messages.` | disabled |

`Panel` impl: `panel_id` is `group-{cache_tag}` so a group opens once; `title` is the avatar
plus the name; `toolbar_buttons` starts empty (Phase 4 fills it).

Validation: `cargo clippy -p nip29_ui --all-targets`, `cargo fmt -p nip29_ui`,
`cargo check -p coop -p coop_web`. The crate is not reachable from the UI until Phase 2, so
review is by code and compile.

---

## Phase 2 — the sidebar and its dialogs

The `Communities` tab becomes one level: a list of groups, a `New Group` dialog and a
`Join Group` dialog. The two-level community view (channels, admins, members, the back
button) is removed; with no channels it has nothing to show, and details move to Phase 4's
dialog.

Files: `crates/workspace/src/sidebar/mod.rs`, `crates/workspace/src/sidebar/tab.rs`,
`crates/workspace/src/lib.rs`, `crates/workspace/src/dialogs/mod.rs`,
`crates/workspace/src/dialogs/new_group.rs` (replaces `new_community.rs`),
`crates/workspace/src/dialogs/join_group.rs`, `crates/workspace/Cargo.toml`.

Add `nip29` and `nip29_ui` to the workspace crate.

`tab.rs`: `Communities` → `Groups`, label and list title `Groups`, list id `sidebar-groups`.
`lib.rs`: `Command::NewCommunity` → `Command::NewGroup`; add `Command::JoinGroup`; both arms
open the dialogs below.

`mod.rs`:

- `SidebarRow::Community { community }` → `SidebarRow::Group { group: Entity<Group> }`.
- Delete `CommunitySection`, `CommunityRow`, `community_scroll`, `channels_open`,
  `admins_open`, `members_open`, `Sidebar::community`, `reset_community`,
  `render_community`, `render_community_rows`, `section_row`, `channel_row`, `member_row`,
  and the back button in `render_user`. `render` loses its community branch.
- `rows_for(Groups)` reads `GroupsRegistry::global(cx).read(cx).groups()` in registry order
  (the `10009` order, then joins).
- The group row: name from `metadata.name()`, falling back to `key.id().as_str()`; avatar from
  `metadata.picture`, seeded with `key.cache_tag()`; suffix for the membership state —
  `Requested` (`Pending`), `Refused`, `Removed`, and `Moved` when `elsewhere().is_some()`;
  nothing for a plain member. Click opens
  `PanelHandle::new(nip29_ui::init(group.clone(), window, cx))` in `DockPlacement::Center`.
- Subscriptions: replace the `CommunityRegistry` subscription with `GroupsRegistry` —
  `GroupsEvent::Updated` → `cx.notify()`, `GroupsEvent::Error(error)` → notification.
- `render_tabs`'s Groups section: `New Group` (`Command::NewGroup`), `Join Group`
  (`Command::JoinGroup`), `Browse` (`Command::ShowBrowse`, still the Phase 3 stub).
- Remove `dialogs/new_community.rs` and its `pub mod` line — nothing dispatches it any more.

The two dialogs, both modeled on `new_community.rs`:

**New group.** Three inputs — name, group id, relay — with ok/validation:

```rust
let id = GroupId::new(if raw_id.is_empty() { slug(&name) } else { raw_id })?;
let relay = RelayUrl::parse(relay_input)?;
registry.create(GroupKey::new(relay, id), GroupMetadata { name: Some(name), ..Default::default() }, cx);
```

A parse failure keeps the dialog open and pushes a notification. The relay's answer arrives
asynchronously as `GroupsEvent::Error(reason)` — the sidebar already shows it. There is no
default relay; the account has no "groups relay" setting yet, so the field starts empty.

**Join.** One naddr input:

```rust
let reference = GroupReference::parse(input)?;   // accepts naddr1…?invite=CODE
GroupsRegistry::global(cx).update(cx, |registry, cx| registry.join(reference, cx));
```

Validation: `cargo check -p workspace`, `cargo clippy -p workspace --all-targets`,
`cargo fmt -p workspace`, then run the app: the tab lists whatever the account's `10009`
holds, no Concord screen is reachable from it, and a pasted naddr joins and opens.

---

## Phase 3 — browse panel

`panels/browse.rs` stops being a stub. `init` takes the dock (`WeakEntity<DockArea>`) the way
`search::init` does, so a joined group can be opened directly.

- Header: relay `Input` + a `Go` button; Enter submits. `RelayUrl::parse` → `registry.browse(relay, cx)`.
- Body: `registry.browsed(&relay)` — a spinner while `Browse::loading`, then rows of
  `GroupCandidate`: avatar, name (or id), `id@relay`, and `Join`
  (`registry.join_key(candidate.key, None, cx)`, then open the panel). Rows for keys already
  in `registry.groups()` show `Joined` instead.
- Subscribes to `GroupsEvent::Updated` and re-renders. Empty state: `No groups found.`;
  before a relay is entered: `Enter a relay to browse its groups.`

Validation: `cargo check -p workspace`; manually browse a public NIP-29 relay and join from a
result, and create a group on a relay that accepts `9007`.

---

## Phase 4 — details, delete, pins, leave

Read-mostly group management, the surfaces the sidebar gave up in Phase 2 plus the two writes
that need Phase 0.

- **Group details** — a dialog or sheet opened from the panel toolbar: name, picture, banner,
  about, flags (`private`, `restricted`, `hidden`, `closed`, `livekit`, `parent`, `children`),
  admins with their role labels (`Group::admins().entries()`), the roles the relay advertises
  (`Group::roles()`), members when the relay publishes `39002` (`Group::members()`), and pins
  (`Group::pins()`). Read-only in this phase.
- **Delete a message** — admin-only entry in the message row's context menu (current user in
  `admins()`) → `group.delete_event(id, cx)`; Phase 0 makes the row disappear.
- **Pin / unpin** — the same menu: `group.update_pins(pins, cx)` with the current list plus or
  minus `Pin::Event(id)`; show `Group::pins()` as a strip above the list.
- **Leave** — toolbar `Leave…` opens a confirmation naming the group (`Leave "Pizza Lovers"?`);
  on confirm `registry.leave(&key, cx)` and the panel closes (dispatch `ClosePanel`, as the
  screening dialog does).
- **Fork / migration banner** — when `group.elsewhere()` is `Some(moved)`, a banner:
  `This group may have moved to {relay}.` with a `Open` button calling
  `registry.join_key(moved, None, cx)`. Never auto-join: the NIP asks the client to offer.

Validation: same commands; manually delete a message, pin and unpin, leave and re-join.

---

## Phase 5 — admin writes

The remaining moderation surface, all through the calls the backend already exposes.

- **Edit metadata** — a dialog started from `group.metadata().cloned().unwrap_or_default()`:
  name, about, picture, the flags. `children` is preserved as-is — `edit_metadata` re-emits
  the full list, and a `9002` that drops one is rejected by the relay.
- **Invite** — `create_invite(code, cx)` with an input or generated code, then
  `metadata.naddr(relay, Some(code))` copied to the clipboard (`naddr` needs parsed metadata;
  a group whose relay publishes no `39000` cannot mint a link).
- **Users and roles** — add by `npub` → `put_user(pubkey, roles, cx)`, remove →
  `remove_user(pubkey, cx)`; role choices come from `Group::roles()`. The relay is the
  authority for both the roles it supports and who may call these.
- **React** — the row menu sends `send_reaction(target, emoji, cx)`; a kind `7` row appears
  inline (that is the current backend behaviour).

Validation: same commands; manually exercise each write against a relay that grants the
account admin, and confirm the refusal path shows the relay's message.

---

## Phase 6 — delete the Concord stack

Nothing in the app may reference Concord before this phase starts.

1. Delete `crates/community`, `crates/concord`, `crates/community_ui`.
2. `crates/workspace/Cargo.toml`: drop `community` and `community_ui`.
   `desktop/Cargo.toml` and `web/Cargo.toml`: drop `community`; `nip29` stays.
3. `desktop/src/main.rs` and `web/src/lib.rs`: drop `community::init(cx)` and its comment.
4. `crates/settings/src/lib.rs`: drop `recent_communities` and `record_recent_community` —
   nothing reads them (verified), and the concept no longer exists.
5. `docs/nip29-usage.md`: replace the "Not wired up yet" section. Remaining known gaps then
   are: LiveKit's response field names (a guess until checked against a real relay), the AV
   room itself, local handling of remote `9005`s, the subgroup tree, and reaction grouping.
6. Confirm no `concord`/`community` string remains outside `docs/` history, and run a full
   `cargo check -p coop -p coop_web` plus `cargo clippy --workspace --all-targets`.

---

## Later (not part of the migration)

- **LiveKit** — `Group::livekit_supported` and `Group::livekit_session` are ready; check
  `metadata.livekit`, then build the AV room UI. Verify the token response fields first.
- **Subgroups** — `parent`/`children` are parsed; assemble the tree in the sidebar when the
  relay advertises `nip29.subgroups`.
- **Replies and threads** — `send_message` already takes reply ids and `chat::Message` reads
  them back; the panel needs a reply affordance and a quoted row.
- **Remote deletions** — fold a `9005` seen live into `Group::forget`, the same eviction as
  Phase 0.
- **Recent groups** — if a local recency list is wanted, store group keys, not the removed
  `recent_communities` strings.

## Validation checklist (every phase)

```sh
cargo clippy -p <touched-crates> --all-targets
cargo fmt -p <touched-crates>          # check the exit code, not the output
cargo check -p coop -p coop_web
```

Plus the manual smoke for the phase, run in the app. The wasm target is not build-verified in
this repo; `coop_web` check is the proxy.

## Decisions taken

- The tab is renamed `Groups`; the vocabulary is the NIP's.
- The sidebar keeps one level; admins and members move to the details dialog.
- The panel reads `Group` directly and keeps no timeline copy.
- Mentions are rendered (shared `chat_ui::text::rendered_text`); replies and attachments are
  not offered for sending in v1.
- `Join` never happens implicitly — not from `10009` alone, and not from `elsewhere()`.
- The old crates are deleted only at the end, so any phase can be stopped and the app still
  runs.