6ab4f0e557
Mirrors mantra.press's multi-file chapter upload under this app's rule that the group, not the uploader, authors the work. The web app's shape -- N files in, N chapters out, one transaction, one redirect -- is the one shape this app cannot have. A signing session is one quorum, all-or-nothing, 64 items and about 64 KiB on the wire, so twelve chapters in one batch does not fit, should not fit, and would ask every member to read twelve chapters in a single approval gate. One upload is N sessions, one per chapter, and that cost belongs in front of whoever is picking files. Reading both trees turned up four things the single-chapter path gets away with at N = 1 and an upload does not: the index is read from rows and no proposed chapter is a row yet, so twelve proposals all sign the same index; nothing checks the proposal's size, which puts a silent ceiling near 28 KiB of markdown; there is no file picker in the app at all; and translation scaffolding opens a session per chapter where one batch would do. The splitter is measured rather than assumed. Run side by side, markdown-it's block tokens and this app's blank-line rule disagree on ten cases in eleven, and on the text as well as the boundaries -- markdown-it strips the block marker, so `# Chapter one` is `"Chapter one"`. Phases 7 and 8 adopt it, with three deliberate departures (no chunk for code blocks, one chunk per table, none for a link reference definition) and a producer, which the app has never had. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
85 lines
9.0 KiB
Markdown
85 lines
9.0 KiB
Markdown
# mantra docs
|
|
|
|
Notes on the parts of this app whose behaviour is not recoverable by reading the
|
|
code alone — where the reasoning lives in a protocol, a failure mode that is
|
|
silent, or a decision that looked arbitrary and was not.
|
|
|
|
| document | covers |
|
|
|---|---|
|
|
| [shared-key-ceremony.md](./shared-key-ceremony.md) | ChillDKG over NIP-17: the rounds, the approval gates, the chat transcript, participant ordering |
|
|
| [shared-key-derivation.md](./shared-key-derivation.md) | deriving further keys from the group's threshold key with FROST tweaks — why not BIP32, why no chain code, and the one rule that must not be broken |
|
|
| [subgroups.md](./subgroups.md) | a group making another group — the four ceremonies, what the parent's signature actually covers, and why the child's key is fresh rather than derived |
|
|
| [frost-batch-signing.md](./frost-batch-signing.md) | signing several events in one ceremony — why one nonce can never cover two messages, and the phased schema, wire and UI work that follows from it |
|
|
| [marmot-membership.md](./marmot-membership.md) | how members join an MLS group, and the epoch race that makes a missing member look like a successful invite |
|
|
| [member-chronicle.md](./member-chronicle.md) | handing a member added after the work was done the group's signed record — why the events are not on the wire at all, and why the room's id is enough to verify them |
|
|
| [marmot-direct-messages.md](./marmot-direct-messages.md) | a one-to-one message inside a group as a stock NIP-59 gift wrap — what its MIP-03 carve-out costs, why the sender cannot read their own, and the one query that would broadcast it |
|
|
| [mls-skipped-keys.md](./mls-skipped-keys.md) | why a group event that arrives a moment late is dropped for good, which flows trigger it, the quartz fix, and the partial mitigation in this app |
|
|
| [long-running-sync.md](./long-running-sync.md) | the chat subscriptions that stay open instead of pulling once per screen — why the request queue could not simply hold one, and how the group filter follows the room list |
|
|
| [dead-code.md](./dead-code.md) | code in the sync and relay stack that nothing calls, why each piece is still there, and which of it is a bug rather than a leftover |
|
|
| [nsec-sign-in.md](./nsec-sign-in.md) | signing in with an existing nostr key — why an nsec can never have a wallet behind it, the ten call sites that make it small, and the sign-in machine that was already built and unreachable |
|
|
| [npub-sign-in.md](./npub-sign-in.md) | signing in with only a public key — what a key that cannot sign can still see here, why that is a preview rather than a browser, and the four decisions the word settles |
|
|
| [multiple-profiles.md](./multiple-profiles.md) | several profiles on one device — why a profile is a credential and a seed is a wallet attached to one, why a switch is a restart rather than a swap, the two entrances the app lacks, and the inbox a switch would silently lose |
|
|
| [jvm-target.md](./jvm-target.md) | what desktop support cost, phased — why the native chain was already done, why an empty source set in our phoenix fork was the real blocker, and why DAO tests need none of it |
|
|
| [npub-profile-preview.md](./npub-profile-preview.md) | showing the person before a direct message is started from a pasted npub — why the preview is a screen keyed by public key, what "found" means when a row can be a placeholder, and the phase that makes the button honest about a key package that never comes |
|
|
| [chapter-uploads.md](./chapter-uploads.md) | picking files off a device and having the group sign each one in as a chapter — why N files can never be one signing session, and the four things the single-chapter path gets away with |
|
|
| [material-design-conformance.md](./material-design-conformance.md) | what the M3 foundations actually require, measured against all 43 screens — the colour pairing that renders the app's own proposals invisible, and eight phases that put the decisions back in the theme |
|
|
| [curated-to-mantra.md](./curated-to-mantra.md) | pulling the Curated fork's thirty-nine commits back under Mantra's names — which lines of work to take, the three decisions, and a measured way to replay a twice-rebranded history without touching seven hundred files by hand |
|
|
| [curated-to-mantra-profiles.md](./curated-to-mantra-profiles.md) | the second pull: the fork's several-profiles line, ten commits and its first schema migration — which of it is a fix Mantra has today, who allocates a schema version number when two trees share one history, and the one conflict, which was Mantra's own |
|
|
| [curated-to-mantra-preview.md](./curated-to-mantra-preview.md) | the third pull: the profile preview and the extended FAB, eleven commits — a brand token hidden in CamelCase, a commit half in a removed line taken as a partial pick, and the two conflicts the compiler found where git saw none |
|
|
|
|
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"
|
|
report — it is silent, and it looks like every other kind of delivery failure. The
|
|
sync note stands alone, and the dead-code inventory reads as a follow-up to it. The
|
|
batch-signing note is a phased plan that has been built: read it after the
|
|
derivation note, whose one rule is the same one it is built around. The member
|
|
chronicle note is a phased plan that has not been built, and reads as the
|
|
membership note's unanswered half: what a member who joins late can be given,
|
|
and the one thing they cannot. The
|
|
jvm-target note is unrelated to all of them: it is a build and packaging story.
|
|
The subgroups note is a phased plan that has been built; it assumes both
|
|
shared-key notes and reads as the ceremony's second half — what a group does
|
|
once it has a key, and what it can say about a group that does not yet.
|
|
The Material Design note is a phased plan that has not been built, and is the
|
|
only one about what the app looks like rather than what it does; read the
|
|
jvm-target note first if you want to know why its adaptive-layout phase exists.
|
|
The curated-to-mantra note is a phased plan that has been built, save for its last
|
|
phase, which is a decision: it is about the repository rather than the app, and reads
|
|
alone, except that its first decision leans on the derivation note's one rule. Two of
|
|
the lines it pulled -- the group's nostr identity and the curated lists -- were taken
|
|
out again the same day, and its record says what went and what stayed. The nsec and
|
|
npub sign-in notes arrived with it and record what they built. The profiles pull note
|
|
is the same exercise a second time, planned with its dry run already done and built
|
|
the same day; read it after the first, because it assumes the method and the three
|
|
decisions and only says what changed — chiefly that the tree is no longer a superset,
|
|
and what the check for an exact pull becomes when it is not. The preview pull note is
|
|
the third and shortest; read it for the two kinds of resolution the first two never needed.
|
|
The nsec sign-in note is a phased plan that has been built; it inherits the
|
|
key-storage decision from the jvm-target note and drives the navigation state
|
|
machine `NavigationViewModel.processLocalAccount` implements, so read it with the
|
|
code open, and read its table of where the build chose differently first.
|
|
The npub sign-in note is a phased plan that has been built, and reads as that
|
|
plan's out-of-scope note answered: it takes the `Identity` type and the sign-in
|
|
machine as given and asks what an identity with no secret is for, before it asks
|
|
how to build one; read its table of where the build chose differently first.
|
|
The multiple-profiles note is a phased plan that has been built, and reads as the
|
|
third of the sign-in notes: it asks what happens when the device holds two
|
|
identities, and its first phase changes one rule the other two share — a seed's
|
|
key becomes a credential like any other — so read it with `StoredIdentity.merge`,
|
|
`SovereignWalletViewModel.switchToIdentity` and the startup screen open, and read
|
|
its table of where the build chose differently first.
|
|
The npub profile preview note is a phased plan that has been built, and is the
|
|
smallest of the plans: it changes the entrance to the direct-message flow and
|
|
nothing past it, so read it with `StartDirectMessageToNpubOrNip05Dialog` and
|
|
`ChatRoomMessagingViewModel.initiateNewChat` open, its four decisions before its
|
|
four phases, and its table of where the build chose differently first.
|
|
The chapter uploads note is a phased plan that has not been built, and is the
|
|
only one that starts from another codebase: it mirrors the mantra.press web app's
|
|
multi-file upload under this app's rule that the group, not the uploader, is the
|
|
author. Read the batch-signing note first — its three limits are the whole shape
|
|
of this one — and read its four-defects section even if the feature is never
|
|
built, because each of those is wrong in the single-chapter path today. Its two
|
|
splitter phases are separable from the rest and worth reading on their own: what
|
|
a chunk is, measured against the parser the web app translates with rather than
|
|
assumed.
|