2 Commits

Author	SHA1	Message	Date
Kgothatso Ngako	45cc80b538	feat(marmot): put a # in front of every group's name, and retire (#admins) ... A device's room list holds two unrelated kinds of room and nothing on a row said which. A NIP-17 room is a conversation between the people in it. A Marmot room is a *group* -- an id its key derives, a membership baked into an MLS tree, admins who can act for it, a signature anyone holding the id can check -- and the two behave differently enough that guessing is a mistake. `"Ekklesia (#admins)"` was an attempt at saying so, and it marked the wrong half. Only the admin room got it; a subgroup got no marker at all, so as soon as a group had one child, half the Marmot rooms on the device were unmarked. It also sorted nowhere near the group it belonged to, and a truncated row drops a trailing suffix first -- so the marker was missing exactly where the list is crowded enough to need it. **The rule is `MarmotGroupName.of`, and it runs where a room is minted rather than where it is drawn.** The name is baked into the epoch-0 `MarmotGroupData` every member is welcomed with, so a `#` added at display time would be a name this device alone could see. `#Ekklesia` marks both kinds of group room, and marks them at the front. **Three mints, because there are three ways a Marmot room comes into existence.** `MarmotGroupCreation.create` is the funnel for two of them -- the admin room a group opens after its ceremony, and a subgroup -- and normalising there means neither caller has to remember. The third, `SelectChatRoomTypeViewModel`'s convenient room, has a random id rather than a derived one, so it has no key state to adopt and no admin set to bake in and does not pass through that funnel; it applies the rule itself. **Idempotence is load-bearing, not tidiness.** A subgroup's name is derived twice from the same bare ceremony-room subject, by two callers that never see each other: `SubgroupManager.proposeBirthCertificate` normalises the name the parent's quorum is asked to sign, and `MarmotGroupCreation` normalises the name the room carries. Those two have to be the same string, or the subgroup is not called what its parent certified -- and a certificate is a signature over the name, so a verifier comparing them would see a real mismatch. `of` being idempotent is what makes them agree by construction rather than by both sites being kept in step. **The ceremony room keeps the bare name.** It is a NIP-17 room -- where a subgroup is made, not the subgroup -- and prefixing it too produced two identically-named rows, which spends the mark to say nothing. `Translators` (the ceremony) now sits beside `#Translators` (the group it stood up), which is the distinction the `#` exists to draw. Its subject is trimmed, so the bare name and the two normalised ones cannot differ by whitespace. **The `#` is drawn beside the name field, not pushed into its state.** `name` in `SelectSubgroupAdminsViewModel` stays bare and the M3 `prefix` slot shows the convention, because normalising on every keystroke moves the caret out from under somebody halfway through a word. The coordinator still reads the name they are about to get. Four strings lose the old name -- "Create the #admins group" becomes "Create the admin room", and the three about what "the #admins room" will sign with now say "the admin room". Their keys are renamed with them, since the keys in this catalogue are derived from the text. Around twenty comments, two screen previews and seven test fixtures follow. Docs: the ceremony note states the convention and what it replaces, and the subgroups note's name-field section is rewritten -- it had been arguing from the `"${parent.subject} (#admins)"` synthesis that no longer exists. `docs/mls-skipped-keys.md` keeps its `"Frosty (#admins)"`: that is a captured debugging log, and rewriting it would falsify a record. Three tests. `MarmotGroupNameTest` pins the rule, idempotence included. `MarmotGroupCreationJvmTest` pins the funnel -- a bare name in, `#Ekklesia` on both the room row this device draws and the group data every other member reads. `SubgroupManagerJvmTest` pins the pair that has to agree, by reading the proposed event's tags back out of the signing session: the name the parent is asked to sign is the name `MarmotGroupCreation` will give the room. That last one needed the signable-parent fixture to seed host keys, since a ceremony's signer ids are derived from them rather than stored. **Rooms that already exist keep their names.** The name lives in the epoch-0 group context, so renaming one is an MLS commit every member has to process -- a different change from a naming convention, and not made here. 403 common tests, 726 jvm tests, `m3Audit` meets every budget with 0 title-case strings and 0 dp literals. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-09-09 11:41:30 +02:00
Kgothatso Ngako	b99cb8fcd5	docs: write down the shared-key subsystem and how Marmot membership fails ... First docs in the repo -- README.md is still the stock KMP template. Three documents plus an index, covering the parts whose behaviour is not recoverable by reading the code: where the reasoning lives in a protocol, where a failure mode is silent, or where a decision looked arbitrary and was not. marmot-membership.md is the one that earns its place. Everything about adding a member compiles, the invite reports success, and a member simply never appears -- and the reason is never in the invite code. It records that inviteMemberToChatRoom hardcodes isOneMemberInitialGroupCreation = false and that ChatRepository does not expose it, so every group invite takes the deferred-welcome path including the first, when the group is still just its creator and the commit has no audience at all. Then why that is silent rather than noisy: MarmotInboundManager refuses future-epoch messages outright, on both wire formats, with no queue and no replay, so a commit arriving before its recipient's welcome is dropped and that member never advances. EPOCH_RETENTION_WINDOW retains past epochs and does nothing for messages from ahead. Three options are set out with the per-invite correctness table, including the honest limit that the recommended one narrows the race without closing it. shared-key-derivation.md argues why the paths are not BIP32 -- no chain code exists, hardened derivation is impossible rather than unimplemented, and a FROST tweak takes the scalar as input so the chain code leaves the problem entirely. It records the x-only serialisation trap avoided by choosing the scalar directly, and states the rule that must not be broken: never reconstruct a derived key in the clear, because k = k' - t hands over the group key rather than one derived key. shared-key-ceremony.md covers the seven kinds, the three approval gates and why the coordinator's aggregations are deliberately not among them, faults as values rather than exceptions, and the transcript's idempotency-by-construction. It also writes down the invariant that produces no error when broken: pendingApproval must mirror the gates in advance, or the screen offers an approval that does nothing -- or none while the ritual sits still. Every factual claim was checked against the source rather than recalled, which turned up one correction worth having: there are two future-epoch refusals, for PrivateMessage and for Commit, so the drop covers both wire formats and not just one. Each document leads with the failure mode rather than the architecture, on the grounds that a failure is what sends somebody to docs in the first place, and each lists its known gaps -- including that none of this has run on a physical device. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-09-05 14:39:19 +02:00