From c64ba8aae4911d7b6fa2a9307d4fa5400b74121d Mon Sep 17 00:00:00 2001 From: Kgothatso Ngako Date: Fri, 20 Nov 2026 02:52:42 +0200 Subject: [PATCH] docs: Phases 8 and 9 are built under the experimental enrollment, and where the build chose differently Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 6 +++--- docs/member-admin-promotion.md | 30 ++++++++++++++++++++---------- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/README.md b/docs/README.md index c2d13410..cf744f01 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,7 +36,7 @@ the [retired](./retired/) notes now. | [marmot-v2.md](./marmot-v2.md) | bringing the group layer onto the Marmot current profile after the quartz 1.15.2 bump — the nine rules that reach this app, why the room's id and the routing id have to become two values, nine phases from reading both profiles to publishing before applying, and the one fork the library cannot yet settle | | [marmot-kmp.md](./marmot-kmp.md) | moving the group layer off quartz's engine and onto marmot-kmp, mls-kmp and crypto-kmp — why staying on quartz 1.15.2 is staying on an engine that left, the 228 import lines and the one rule that places all but two of them, the group state on a device that must still open afterwards, nine phases that put the swap in one commit and the evidence around it, how often this app persists a group once a sent message no longer rewrites it, and the schema change that followed, opened from the version the app ships | | [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 | -| [member-admin-promotion.md](./member-admin-promotion.md) | making a member an admin and back, phased and built but for promotion with a share and demotion with a refresh, under three rules: every admin holds a share, every commit in a keyed room is a proposal until the group's threshold signature is on it, and a robust group keeps at least three admins. Covers why the commit rides inside the group's signature and the rule inside the group's state, which lets every device refuse an unsigned commit with the libraries as they are, why a member's own leave stays exempt, and why a removed admin comes back as an admin when re-invited today | +| [member-admin-promotion.md](./member-admin-promotion.md) | making a member an admin and back, phased and built, promotion with a share and demotion with a refresh under the experimental enrollment, under three rules: every admin holds a share, every commit in a keyed room is a proposal until the group's threshold signature is on it, and a robust group keeps at least three admins. Covers why the commit rides inside the group's signature and the rule inside the group's state, which lets every device refuse an unsigned commit with the libraries as they are, why a member's own leave stays exempt, and why a removed admin comes back as an admin when re-invited today | | [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 | @@ -106,8 +106,8 @@ that phase, and its table of findings before any phase. Its second half removes the nip30303 documents and leaves the member chronicle built but carrying no kinds, so read it before building on the chronicle note. -The member-admin-promotion note is a phased plan built but for its share work (Phases 8 -and 9), which waits on enrollment leaving experimental. It reads as +The member-admin-promotion note is a phased plan built but for a keyed room's admin +leaving; its share work (Phases 8 and 9) is behind the experimental enrollment. It reads as the Marmot v2 note's Phase 7 finished, and as the share-refresh note put to work: a promotion is an enrollment and a demotion is a refresh. Read its three rules and its headline before any phase. Its headline is the one idea the keyed-room half stands diff --git a/docs/member-admin-promotion.md b/docs/member-admin-promotion.md index 8097ab35..e5a0f022 100644 --- a/docs/member-admin-promotion.md +++ b/docs/member-admin-promotion.md @@ -4,22 +4,25 @@ A plan for promoting a member of a group to admin and demoting an admin back to member. It also covers the jobs that need the same machinery: removing an admin, an admin stepping down, and an admin leaving. -**A phased plan, built but for its share work.** Written against the code as it stood at `fc437d05`, with +**A phased plan, built but for its keyed-room leave.** Written against the code as it stood at `fc437d05`, with marmot-kmp 2.2.1 and mls-kmp 1.3.0 as the catalogue pins them. The second draft adds three rules the first draft lacked; they are stated in the next section, and most of the plan follows from them. **Built**, one commit per phase on `claude/member-admin-promotion-plan-d9d716`: the first release's phases (10a, 1, 2, 6, and 10 and 11 for convenient rooms), Phases 3, 4a, -4b, 5 and 5b, and Phase 7 on both sides (the app's refusals, and the floor every device -holds a commit to at the door). The first draft's Phase 0 -- upstream work in mls-kmp and -marmot-kmp -- was dropped when the commit moved inside the signature (the headline). -**Not built:** Phases 8 and 9 (promotion with a share, demotion with a refresh, both -behind enrollment and refresh leaving experimental), Phase 10's keyed-room rows, and -Phase 12. **Not run:** nothing here has been on a device, and no test runs a real FROST -ceremony through `GovernanceManager.propose` -- the tests stand a key pair in for the -room's aggregated key, which is all a FROST signature is once made, and drive the steps -either side of the session. +4b, 5 and 5b, Phase 7 on both sides, and Phases 8 and 9 under the experimental FROST +enrollment (`ExperimentalFeatures.shareRefresh`, off in release). The first draft's +Phase 0 -- upstream work in mls-kmp and marmot-kmp -- was dropped when the commit moved +inside the signature (the headline). **Not built:** Phase 10's keyed-room rows (an admin +of a keyed room still cannot step down or leave) and Phase 12. **Not run:** nothing here +has been on a device. The enrollment itself is tested end to end with real reduced FROST +across in-memory devices (`ShareRefreshRitualJvmTest`): a member who never took part in +the ceremony is enrolled at the next id and signs. What no test runs is the whole +promotion in one go -- offer, acceptance, the signed batch through +`GovernanceManager.propose`, the commit, then the enrollment -- since the governed-room +tests stand a key pair in for the room's key and the enrollment tests run in a room +that is not governed; each half is tested on its own. Where the build chose differently: @@ -42,6 +45,13 @@ Where the build chose differently: | Phase 6's removal of an admin is "chained in memory" | through `MarmotEngine.afterConfirmed`, registered *before* the commit it waits on so a relay's OK cannot overtake it, and taken back if publishing throws. Leaving as an admin uses the same hook. In a governed room a removal is one signed commit instead | | Phase 7's floor is checked on demotion, removal and leaving | on removal and on every governed commit at the door; a keyed room offers no demotion and no leave for an admin until Phases 8 to 10 | | Phase 10's keyed-room rows: "above the floor" and "at the floor" | one row for now. A keyed room's admin who presses **Leave group** is told, as before, that an admin cannot leave; `AdminLeave.CANNOT` | +| Phase 8: promotion from any keyed room | only from a key past its ceremony's generation. Generation 0 lives in the ceremony's own record, which has no room for an id the ceremony did not make; the first rotation makes the generation rows an enrollment extends. **Make admin** says so when it is refused | +| Phase 8: offer and acceptance as "a new 303xx kind" | 30374 and 30375, and a third, 30376, for the **handover**: once the change lands, the offering device sends the new admin the table, roster and signed key state. The new member's device holds nothing of the key before that, and checks all of it against the room's own signature -- the state has to be one the room signed, the table has to hash to what it names, and it has to bind the new id to this account under this device's host key | +| Phase 8: `P_n` "interpolated in the exponent from the existing table" | from the table's first `t` entries, with `FrostEnrollment.derivePublicShare`. Every device does it, and adds the id only when the extended table hashes to what the group signed | +| Phase 8: enrollment as `ShareRepairManager` generalised | the repair protocol unchanged but for its `n`: a request names the `n` it runs with (the new id, the table's size before it), helpers check that against their own table, and an enrollment asks no helper for approval -- the signed binding was everyone's chance to say no | +| Phase 8: `n` grows in "the stored key" | a signing session's and a repair's `n` is the generation's table size, which the enrollment grew; the ceremony's `participantCount` is left as the ceremony made it | +| Phase 9: every remaining holder's deal and confirm made automatic | the rotation is started by the proposer's device once the change lands (`GovernanceFollowThrough`), and each holder is asked once to take part, as every rotation now asks (rotate-shares-single-approval). A rotation that cannot start is said in the room and offered from the Shares section | +| Phase 9: an admin can step down in a keyed room | not offered. The rotation that has to follow is the remaining holders', so another admin proposes the demotion | | Phase 11's dialogs for every action | removal keeps the immediate action it had; promotion, demotion and stepping down ask first | Read [marmot-v2.md](./marmot-v2.md) Phase 7 first. Removing a member, disbanding and