docs: plan to make every group a member creates robust (remove-convenient-groups)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-20 02:00:08 +02:00
1 parent e78dfe50cf
commit 9008d4fe19
2 files changed
+368

No files matched your search

+1
View File
@@ -38,6 +38,7 @@ the [retired](./retired/) notes now.
| [giza-wallet-removal.md](./giza-wallet-removal.md) | taking every wallet out of Giza, phased and built but for moving off the wallet library (7b). Covers why a Giza member declines a Bennu peer's wallet proposal instead of ignoring or signing it, why the wallet's kinds are retired rather than freed, why a recovery phrase stays as a key backup that has to derive the same npub and id byte for byte, and why the threshold crypto keeps the build tied to the wallet library until the last phase |
| [giza-rebrand.md](./giza-rebrand.md) | forking Bennu as Giza under `mobi.giza` — what carries the name, what must not be renamed and why, why the desktop data directory changes first, and how the fork keeps merging from Bennu |
| [robust-group-admins.md](./robust-group-admins.md) | making every founding member of a robust group an admin of its room, on every device -- phased and built. Covers why the ceremony's participants are the founding set, the Welcome that flags no admins, the joiner's check against the ceremony it took part in, and finishing an invite that partly failed |
| [remove-convenient-groups.md](./remove-convenient-groups.md) | every group a member makes is robust -- a phased plan, not built. Covers why a one-to-one chat is not a group, why the three-member floor moves to the member picker rather than down to 2-of-2, the quorum rules that outlive `ChatRoomType`, and why a Bennu peer's convenient group is still joined |
Start with the ceremony if you are new to this area; the Marmot notes all assume it.
Read the skipped-keys note before debugging any "the other device never got it"
+367
View File
@@ -0,0 +1,367 @@
# Every group a member makes is robust
Group creation ends on a choice between two kinds of group: **convenient**, which the
creator runs alone, and **robust**, which every member runs together under a t-of-n
key. This note is the plan that takes the choice away. Every group a Giza member makes
will be robust, on a threshold they pick, and convenient will survive only as
something Giza can still join, read and leave.
**Not built.** Written against `e78dfe50`.
Read [robust-group-admins.md](./robust-group-admins.md) first; it describes what a robust
group is in the code, and this plan leaves that unchanged. [subgroups.md](./subgroups.md)
holds the reasoning for the three-member floor that Phase 3 moves.
## What a convenient group is, in the code
A convenient group is one Marmot room with one admin and no key.
```
SelectChatRoomTypeViewModel.createChatRoom
│
├─ CONVENIENT → createMarmotChatRoom
│ ├─ MarmotGroupFactory.create roomId = random, adminPublicKeys = [creator]
│ └─ inviteMembers key packages, one addMembers commit
│
└─ ROBUST → createNip17ChatRoom
├─ chatRepository.createNip17ChatRoom
└─ dkgRepository.proposeRitual(threshold = quorum)
└─ … the admin room, made by MarmotGroupCreation once the key exists
```
It is the screen's default (`selectedChatRoomType = CONVENIENT`) and the only choice
for a group of fewer than three people (`ChatRoomType.isRobustAvailable`).
`ChatRoomType` is **not persisted** and **not in a route**. Nothing on a device records
that a room was made convenient. A convenient room is just a Marmot room with no
`GroupKeyState`, which `FoundingAdmins.Check.NotKeyBacked` names.
Three sites call `MarmotGroupFactory.create`:
| site | room | admins | key behind it |
|---|---|---|---|
| `SelectChatRoomTypeViewModel.createMarmotChatRoom` | a convenient group | the creator | none |
| `MarmotOutboundDao.createMlsDirectMessageChatRoom` | a one-to-one chat started from a profile | the creator | none |
| `MarmotGroupCreation.create` | a robust group's admin room, or a subgroup's | the ceremony's participants | the threshold key, which the room's id is derived from |
Only the first is the subject of this plan. The second is discussed under D1.
`ChatRoomType`'s companion is not about convenient groups at all. It holds the quorum
rules, and `ChillDkgRitualManager`, `CreateSharedKeyViewModel`,
`SelectSubgroupAdminsViewModel` and `SubgroupManager`'s KDoc depend on them:
`MINIMUM_ROBUST_GROUP_SIZE`, `MINIMUM_QUORUM`, `defaultQuorum`, `quorumRange` and
`isRobustAvailable`. Those rules stay. Only the enum goes.
## Decisions
**D1. "A group a user creates" means the group-creation flow. A one-to-one chat is not a
group.** `createMlsDirectMessageChatRoom` makes a two-member room whose creator is its
only admin, which is structurally a convenient group. It stays as it is because:
- two people cannot carry a meaningful threshold (D2), so the robust alternative is a
2-of-2 key that freezes the chat the day one phone is lost;
- the app has no path that adds a third member to an existing room (`addMembers` is
called only at creation, by `SelectChatRoomTypeViewModel` and `MarmotGroupCreation`),
so a one-to-one chat cannot grow into a group run by one person.
Phase 2 records the second point as a test, so that adding an "add member" action
later is a decision someone makes in that test, not a side effect.
Confirmed before any phase was built. If one-to-one chats should ever be robust too,
that is a separate plan: a 2-of-2 key, the ceremony started from a profile, and an
answer for a peer who never comes online.
**D2. The floor stays at three people, the creator included, and moves to the member
picker.** `ChillDkgRitualManager.MINIMUM_PARTICIPANTS` would accept 2-of-2, but the app
has decided three separate times that two is not a group worth a quorum
(`ChatRoomType.MINIMUM_ROBUST_GROUP_SIZE`, `SubgroupManager.MINIMUM_ADMINS`,
[subgroups.md](./subgroups.md)). The reason holds here too: 2-of-2 means either member
can freeze the group by going quiet. Today a group of fewer than three people becomes
convenient without anyone choosing it. After this plan, the picker will not let a group
of fewer than three be made at all, and will say why, pointing anyone with only one
person in mind at a direct message. Confirmed before any phase was built.
**D3. Convenient rooms that already exist keep working, unchanged.** That covers rooms
this device made before the change and rooms a Bennu peer makes and invites a Giza
member into. Receiving, reading, sending, leaving and the creator's own governance
(removing a member, disbanding) all stay. There is no migration, and there is **no
upgrade path**. A Marmot room cannot host its own ceremony
(`ChillDkgRitualManager.proposeRitual` requires it, see
[ceremony-creation.md](./ceremony-creation.md)), and a robust room's id is derived from
its key. "Make this group robust" therefore means making a new group with the same
people. That is a possible follow-up, not part of this plan.
**D4. Bennu peers are not declined.** This is unlike a wallet
([giza-wallet-removal.md](./giza-wallet-removal.md)): a convenient group is something
Giza fully understands and can take part in honestly. Giza stops *making* convenient
groups. It does not refuse to join them.
**D5. No wire change and no schema change.** `ChatRoomType` was never written anywhere,
so deleting it touches no stored row, no route argument and no event.
**D6. The quorum rules get a home of their own before the enum goes.** They move to a
new `Quorum` object in `managers/`, next to `ChillDkgRitualManager`, which enforces them.
They move in a phase of their own (Phase 1), so the deletion in Phase 4 changes no
behaviour.
## What changes for a person making a group
| step | today | after |
|---|---|---|
| name and description | unchanged | unchanged |
| pick members | any number, including none. "You can still carry on and invite people" | at least two others. The button is disabled below that, with the reason shown. The "carry on and invite later" line goes, because nothing would offer the invite |
| how the group is run | two cards, convenient selected. Robust disabled below three, with a quorum stepper under it | one screen asking how many of the *n* have to agree, starting on a simple majority |
| create | convenient: a Marmot room plus invites, and a card listing who could not be added. Robust: a NIP-17 room plus the ceremony | always the NIP-17 room plus the ceremony. The "ceremony couldn't be started" card stays |
## Phases
One commit per phase. Each phase ends with:
```bash
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
```
Phases that touch UI also end with:
```bash
./gradlew :composeApp:m3Audit
```
### Phase 0: pin the target in failing tests
**Add** `composeApp/src/jvmTest/kotlin/mobi/giza/compose/ui/view/model/GroupCreationJvmTest.kt`,
on the fake-repository pattern `SelectSubgroupAdminsViewModelJvmTest` uses. Use a
recording `ChatRepository` and `DkgRepository`, and three members plus the creator:
- `creating a group opens a NIP-17 room and its key ceremony`: with no choice made,
`createChatRoom` calls `createNip17ChatRoom` once and `proposeRitual` once, with
`threshold == Quorum.defaultQuorum(4)`. It never calls `addMembers` or
`observeMarmotKeyPackageForPublicKey`. **Fails today**, because the default is
convenient. Mark it `@Ignore("Phase 2")`.
- `the quorum picked is the quorum asked for`: set the quorum to 4 of 4 and assert
`proposeRitual(threshold = 4)`. This passes today if robust is selected first.
- `a group below the floor is never created`: build the view model with one member
and assert no repository call and an `Error` state. Mark it `@Ignore("Phase 2")`.
**Add** `composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/MarmotRoomEntryPointsJvmTest.kt`,
modelled on `CeremonyEntryPointsJvmTest`. It counts the files in `commonMain` that call
`MarmotGroupFactory.create(` and asserts exactly
`{MarmotGroupCreation, MarmotOutboundDao}`. Mark it `@Ignore("Phase 2")`, because
`SelectChatRoomTypeViewModel` is the third today. Its KDoc says what each caller is for,
and that the one-to-one chat is the only room without a key (D1).
**Done when** both files exist, the parts that pass today pass, and each ignored test
names its phase.
### Phase 1: `Quorum` takes the rules (D6)
**Add** `managers/Quorum.kt`:
```kotlin
object Quorum {
const val MINIMUM_GROUP_SIZE = 3 // was ChatRoomType.MINIMUM_ROBUST_GROUP_SIZE
const val MINIMUM = 2 // was ChatRoomType.MINIMUM_QUORUM
fun default(memberCount: Int): Int // was defaultQuorum
fun range(memberCount: Int): IntRange // was quorumRange
fun isPossible(memberCount: Int): Boolean // was isRobustAvailable
}
```
The KDoc for each rule moves with it and gets rewritten without the word "convenient".
The reason a single approval is not a quorum stays: one person acting alone.
**Change** every caller to use it: `ChillDkgRitualManager` (three sites),
`CreateSharedKeyViewModel`, `SelectSubgroupAdminsViewModel` and
`SelectChatRoomTypeViewModel`. `SubgroupManager.MINIMUM_ADMINS` becomes
`= Quorum.MINIMUM_GROUP_SIZE`, so the floor is stated once and the KDoc points to it
instead of repeating it. `ChatRoomType` keeps its two values and loses its companion.
**Tests.** Add `QuorumTest` (commonTest): `default` is a simple majority and never
below `MINIMUM` for sizes 2 to 9, `range` runs from `MINIMUM` to *n*, and `isPossible`
flips at 3. `CreateSharedKeyViewModelJvmTest`, `SelectSubgroupAdminsViewModelJvmTest`
and `SubgroupManagerJvmTest` keep passing unchanged.
**Done when** nothing outside `SelectChatRoomType*` imports `ChatRoomType`.
### Phase 2: creation is always robust
**`SelectChatRoomTypeViewModel`**:
- Delete `selectedChatRoomType`, `selectChatRoomType`, `createMarmotChatRoom`,
`inviteMembers`, `membersNotAdded`, `robustUnavailableReason` and
`KEY_PACKAGE_LOOKUP_TIMEOUT`, along with the imports only they used
(`MarmotGroupFactory`, `MarmotGroupName`, `RandomInstance`, `MarmotProfile`,
`Relays`, `withTimeoutOrNull`, `async`/`awaitAll`).
- `createChatRoom` goes straight to what is now `createNip17ChatRoom`. Rename it
`createGroup`, because the NIP-17 room is how a group is made, not one option among
several. Keep the KDoc: it is the reasoning for opening the ceremony at once.
- In `initiate`, a member set below `Quorum.MINIMUM_GROUP_SIZE` sets
`SelectChatRoomTypeUIState.Error` and makes no repository call. The picker stops
this in Phase 3, but a route can still be built by hand, and the ceremony would
refuse it later anyway (`ChillDkgRitualManager` requires the range). Failing on the
screen is the honest place for it.
- Keep `keyCeremonyNotStarted`, `createdChatRoomId` and the idempotent second tap,
unchanged.
**`SelectChatRoomTypeScreen`**:
- Delete both `ChatRoomTypeCard`s and the composable itself. The `QuorumPicker`
becomes the screen's content: a heading, the stepper, and the explanation, which
`quorumExplanation()` already writes.
- Delete the `membersNotAdded` error card. The NIP-17 room has nobody to invite, and
the admin room's partial invites are `CeremonyFollowThrough` step 4's job
([robust-group-admins.md](./robust-group-admins.md), Phase 4).
- Keep the `keyCeremonyNotStarted` card and its `start_the_key_ceremony` button.
- Replace the error branch's bare `Text` with `ErrorState(onRetry = null)`. The error is
structural and retrying will not help. Passing `null` is the decision CLAUDE.md asks
for.
- Move the footnote that was on the robust card under the picker as body text, worded
for a screen with no alternative: "No one can change the group alone, and it outlives
any one of you. Creating it starts a key ceremony every member takes part in."
- Strings, sentence case, all new in `strings.xml`: the screen title ("How many of you
have to agree?"), the footnote, the FAB's "Create group", and the stepper's two
`contentDescription`s, which are literals today. Delete
`this_decides_who_can_change_the_group_later`, `just_you_for_now`,
`you_and_1_other` and `was_created_but_couldn_t_be_added_yet_invite`.
`how_should_be_run` goes too: the title no longer asks how the group is run.
- The preview gets a third member so it renders at the floor.
**Un-ignore** both Phase 0 tests. `MarmotRoomEntryPointsJvmTest` now passes with two
minters.
**Add** to `MarmotRoomEntryPointsJvmTest`: `members are added to a room only at its
founding`. It asserts that `chatRepository.addMembers(` is called only from
`MarmotGroupCreation`. This is the test that keeps D1 true: a one-to-one chat cannot
become a group without someone changing this line.
**Done when** no path through the app makes a Marmot room with a single admin and
more than one member.
### Phase 3: the member picker holds the floor (D2)
**`SelectChatRoomMembersViewModel`**:
- Add `val minimumOthers = Quorum.MINIMUM_GROUP_SIZE - 1` and
`fun canContinue() = selectedPublicKeys.size >= minimumOthers`. The creator counts
toward the floor, as in `SubgroupManager`: asking for three *others* would quietly
build a group of four.
- `selectChatRoomType` returns early unless `canContinue()`, matching
`SelectChatRoomTypeViewModel.selectChatRoomType`'s old guard against a disabled card
being tapped anyway.
- Rewrite the key-package prefetch's comment, but keep the prefetch. The NIP-17 room
needs no key packages, but the admin room `MarmotGroupCreation` makes after the
ceremony does. Fetching them here means they are usually on the device by then.
**`SelectChatRoomMembersScreen`**:
- The FAB gets `enabled = canContinue()`. `ExtendedFab` already takes `enabled`.
- The bottom bar's supporting text says what is still missing. It reads "Pick at least
2 people" with nobody selected, "Pick 1 more" with one, and the existing
"%1$s selected" from two up.
- The empty state, which shows when the store has no profiles, drops
`you_can_still_carry_on_and_invite_people`. That line becomes false, because there is
no later invite. It is replaced with a line saying a group needs at least two other
people, and that searching for someone or starting a chat with them adds them here.
The same message, through `EmptyState`, covers a store with exactly one profile,
where a group could never be made.
**Tests.** Add `SelectChatRoomMembersViewModelJvmTest`:
- `the picker does not continue with fewer than two others`: one selected leads to no
navigation.
- `two others is enough`: two selected leads to a `SelectChatRoomTypeRoute` carrying
both.
- `the creator is not counted twice`: the active user is excluded from `profiles` and
never counted.
**Done when** the only way to reach the quorum screen is with a group the ceremony
will accept.
### Phase 4: `ChatRoomType` goes, and the names follow
- Delete `database/model/types/ChatRoomType.kt`.
- Rename the screen to what it now does. `SelectChatRoomType{Screen,ViewModel,UIState,Route}`
becomes `SelectQuorum{Screen,ViewModel,UIState,Route}`, and
`SelectChatRoomMembersViewModel.selectChatRoomType` becomes `selectQuorum`. Update
`GizaNavHost` and the route's `@Serializable` name. Nothing persists a route across
an upgrade, so the rename is safe. Check this against `NavigationIdentityRoutingJvmTest`
before relying on it.
- `CeremonyEntryPointsJvmTest`'s expected set names `SelectQuorumViewModel`.
- `MarmotGroupFactory`'s KDoc says two sites make rooms, not three.
`FoundingAdmins.Check.NotKeyBacked` now reads: "No key behind the room: a one-to-one
chat, a group made before every group was robust, or one a Bennu peer made. Run by
its creator."
- Run `docs/scripts/m3-audit.sh`. The literals report should drop by the strings the
two cards held.
**Done when** `git grep -i convenient -- composeApp` finds nothing but
`FrostSigningSession` and `GroupKeyStateEvent`, which use the ordinary English word.
### Phase 5: rooms that are already convenient (D3)
No migration. These are the visible effects only:
- **Detail screen.** A room whose `FoundingAdmins.check` is `NotKeyBacked`, with more
than two members, shows one line of supporting text under its members: "Run by
%1$s alone. Changes don't need anyone else's approval." It names the creator from
`currentAdminIdentities()`. Without this line, the app no longer explains anywhere
why this group behaves differently from every other group the member is in. A
two-member room (D1) shows nothing, because a one-to-one chat being run by one
person is not news.
- **Creator governance is unchanged.** `canGovern` still reads `isLocalAdmin()`, so the
creator of a convenient room can still remove members and disband it.
- **Bennu invites are unchanged** (D4). Add a case to `WelcomeBundleMatchJvmTest` or
`MarmotGroupFactoryJvmTest`: `a single-admin group made elsewhere is still joined`.
It builds a room with `adminPublicKeys = [creator]` and three members, delivers the
Welcome, and asserts the joiner holds the room and `FoundingAdmins.check` is
`NotKeyBacked`. This pins D4 so a later cleanup cannot take the join path out with
the creation path.
**Done when** a member can tell a legacy convenient group from a robust one on its
detail screen, and a Bennu peer's convenient group still reaches them.
### Phase 6: docs
- This note: mark it built, with a table of where the build differed from the plan.
- [robust-group-admins.md](./robust-group-admins.md): the diagram's first line names
the renamed view model, and "Out of scope: Convenient groups" points here.
- [subgroups.md](./subgroups.md) (lines 801 and 859),
[ceremony-creation.md](./ceremony-creation.md) (127 and 279),
[shared-key-ceremony.md](./shared-key-ceremony.md) (158) and
[marmot-membership.md](./marmot-membership.md) (108): rename
`SelectChatRoomTypeViewModel` and `ChatRoomType.MINIMUM_ROBUST_GROUP_SIZE`. The
marmot-membership mention of `inviteMembers` at creation now refers to
`MarmotGroupCreation` only.
- Leave [marmot-v2.md](./marmot-v2.md)'s and [nsec-sign-in.md](./nsec-sign-in.md)'s
links to `createMarmotChatRoom` alone. They are history and say what was true when
they were written. Add a parenthetical saying it was removed here.
- [README.md](./README.md): the table row, which this commit adds, says "built".
## Out of scope
- **One-to-one chats** (D1). If they are to become robust, that needs its own plan.
- **Upgrading an existing convenient group** (D3). A new group is the way.
- **Gating MLS commits in the admin room on the quorum.** Every founding member of a
robust group is an admin, and any one admin can commit a change to the admin room
alone. `canGovern` is `isLocalAdmin()`. The quorum governs the key: key states,
subgroup certificates and share rotations. It does not govern each MLS commit. The
creation screen's promise that "any change … has to be approved by a quorum" is
therefore stronger than the code. Phase 2 removes that sentence with the robust card,
and the new footnote claims only what the key enforces. Making the claim true for
membership is a separate piece of work.
- **Declining Bennu's convenient groups** (D4).
## Risks
- **People with one contact.** Someone who has spoken to only one other person can no
longer make a group with them, only a direct message. That is D2's cost, and
Phase 3's empty state says so rather than leaving a disabled button unexplained.
- **The ceremony is now the only way to make a group.** A group is not usable as a
governed group until enough members have come online for the ceremony. The NIP-17
room works for chat at once, as it does for robust groups today. Groups that used to
be convenient were usable the moment they were created. If that delay turns out to
matter, the fix belongs in the ceremony
([automatic-key-ceremony.md](./automatic-key-ceremony.md)), not in bringing back a
creator-run kind.
- **Merges from Bennu.** Bennu keeps `ChatRoomType` and the convenient path. A merge
that brings `createMarmotChatRoom` back will fail `MarmotRoomEntryPointsJvmTest`,
which is the purpose of that test. Resolve it in favour of this plan.