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
# 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 |
docs: plan subgroups, and phase the four ceremonies a group needs to make one
A group can make another group, and the child can prove where it came from. This
is the plan for that, in nine phases, written against the code at b50b1762 and
not yet built.
**A subgroup is an ordinary robust group plus one artefact.** Fresh ChillDKG key,
fresh room, fresh quorum, and a birth certificate -- the parent's signature over
the child's room id -- carried on the child's `GroupKeyState`. Deriving the child
at `m/9420/1/0` instead would cost no ceremony at all and was rejected: a derived
child is the parent wearing a different hat, administered by the parent's members
with the parent's quorum, when the whole point is that a different set of people
can act on their own. The certificate is a claim about lineage, never a
delegation of authority, and nothing here lets one group sign for the other.
**Four steps, in the only order they can happen.** The ceremony produces `K`, so
the child's id exists; the parent's quorum certifies that id; the child's quorum
signs a key state carrying the certificate; the coordinator creates the room. No
step is a policy choice -- each needs the one before it -- and the last is gated
on the key state for the same reason `createAdminGroup` already is.
**What the parent's admins actually sign is the argument that shaped the event.**
Taken literally the certificate is 32 opaque bytes produced by a ceremony most of
them were not in. So the content is exactly the new group id as specified, and
the tags carry the child's threshold key, the path and the admin set -- covered
by the same signature, since an id hashes over its tags -- which lets a signer's
device check `marmotGroupId(key, path) == content` before agreeing, and lets a
coordinator who lies about who is in the child do it in a field the parent's
signature covers.
**The whole certificate travels as JSON on the key state, not a bare signature.**
A signature plus a rule for rebuilding the event it covers is a rule that breaks
silently the first time the event's shape changes: a rebuild differing by one
byte hashes to an id whose signature fails, and is indistinguishable from a
forgery. A parent tag rides beside it as an index into the certificate rather
than a second source of truth -- Phase 3 drops any state carrying one without the
other, or the two disagreeing, so there is no state where the index is believed
and the certificate is not.
**The ceremony stays on gift wraps, and the reason is `mls-skipped-keys.md`.**
Holding all three steps in the parent's Marmot room is the better design and the
plan says so at length rather than dismissing it: the certificate already runs
there, and the key state and the ceremony move together or not at all, since both
`GroupKeyStateManager.propose` and `signingPath` tie a key state to the room its
ceremony ran in. The mechanical cost is three enumerable changes. The reason to
wait is that the skipped-keys note already lists `proposeRitual` as a reliable
trigger, and a DKG cannot finish without every participant -- so one message
dropped for good stalls it permanently, where FROST needs `t` of `n` and routes
around a lost nonce. Revisit when the quartz fix lands; the collision Phase 4
refuses disappears with it.
**Three admins in total, and the threshold is set before anything is published.**
Three is `ChatRoomType.MINIMUM_ROBUST_GROUP_SIZE` for the reason that constant
gives, and the coordinator counts because they hold a share by construction, so
the picker asks for two others. `t` has to be chosen on that same screen and
nowhere later: ChillDKG hashes it and the host keys into the session identity, so
it is fixed the moment the proposal goes out, and a group that disagrees about it
gets no key rather than a weak one.
The nine phases are ordered so the checkable parts come first and can ship dark:
the certificate and its verifier are pure, the schema is three nullable columns,
and nothing produces a certificate until the button in Phase 7 exists. Phase 6
extracts the 120 lines of Marmot room creation out of `DkgRitualViewModel` so
both flows share the rules that are already right there.
What it does not do is named rather than left to be found: no revocation, no
delegation, certificates are not chroniclable, one subgroup per admin set, and
every selected admin has to show up twice.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 22:53:31 +02:00
| [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 |
feat(frost): move a signing session's per-event columns onto FrostSigningItem
Phase 1 of docs/frost-batch-signing.md, which is added here as the plan the
next phases follow. Schema only: a session still signs exactly one event, the
wire is byte-identical, and every existing test passes on the moved columns.
## What moved, and why it had to
A batch of k events is k independent FROST instances sharing a signer set, not
one signature over k messages. That is forced rather than chosen: a Schnorr
partial signature is `s = k + e·x` with `e = H(R‖P‖m)`, so two messages under
one nonce R give two equations in one unknown and the secret share falls out.
So the five columns that enter that equation -- unsignedEventJson, eventId,
nonceRandom, aggregatedNonce, signature -- move to a child table keyed
(sessionId, itemIndex). What stays on FrostSigningSession is everything outside
it: the ceremony, the threshold, the derivation path, the signer set, and the
one approval.
itemIndex is protocol rather than presentation -- nonces and partial signatures
are joined positionally against it -- so getItems() orders by it and nothing
re-sorts. Spelled itemIndex rather than index to keep hand-written queries free
of backticks.
No itemCount column. The count is a COUNT(*), for the same reason signerIds is
derived from the ceremony's participant order rather than stored: a
denormalised count is one more thing that can disagree with the rows.
## Migration 9 -> 10
Manual, not auto: Room can create the table and drop the columns but cannot
copy between them, and the copy is the whole point. A session in flight at
upgrade holds its nonce seed and the aggregate it is already signing against,
and neither can be regenerated -- losing either makes the next pass derive a
different nonce for the same message and publish a second partial signature
over it, which is the extraction case. Both are copied verbatim into item 0, so
an in-flight session resumes as though nothing happened.
Removing the columns uses ALTER TABLE DROP COLUMN rather than the usual
create-copy-drop-rename rebuild. FrostSignerMessage and FrostSigningItem both
reference FrostSigningSession(id) ON DELETE CASCADE, and DROP TABLE fires
cascades -- with foreign keys enforced the rebuild would delete every signer
message and every item just written. Whether it does depends on Room disabling
foreign keys around migrations, which is not worth depending on when
DROP COLUMN cannot go wrong. It needs SQLite 3.35 and unindexed,
unconstrained columns; these five qualify, and getRoomDatabase pins
BundledSQLiteDriver on every platform.
## Invariants established here for the phases that follow
- signerIds and every item's aggregatedNonce are one write-once unit, applied
by applyAggregate() -- items first in one transaction, then the session, so
"some items aggregated" is unreachable and signerIds != null stays the gate.
- Signatures likewise, via applySignatures(); isSigned() counts rows instead of
reading a flag.
- complete() verifies every signature before applying any event, so a batch is
all-or-nothing rather than half-filed.
- itemsOver() gives each item its own 32 bytes of seed. Independent seeds mean
an off-by-one in index handling produces a session that fails to aggregate
rather than one that signs two messages under a single nonce.
signedEvent() and isAwaitingApproval() now take the item(s) rather than the
session, which propagates to the repository, the view model and the screen.
advance() reads items.first() and Phase 2 turns that into a loop.
## Tests
- FrostSigningSessionDaoJvmTest: index ordering, single-item read, upsert
replacing rather than accumulating, signed-item counting, cascade delete.
- FrostSigningItemMigrationJvmTest (new): the backfill against a real v9
database, asserting the seed and aggregate values survive -- not merely that
a row appeared -- plus the exact column lists Room will check at open time.
- 338 jvmTest and 217 testDebugUnitTest pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 04:33:46 +02:00
| [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 |
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
| [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 |
refactor: call it a chronicle, and keep "archive" for what a user does to a chat
Archiving a chat is an ordinary thing a user will want to do to a conversation,
and it is not this. This is the group's signed record, handed to a member who
joined after the work was done so their room stops being empty. Two unrelated
meanings of one word in one app is a bug waiting to be written, and
`ChatRoom.archiveRequestedAt` is exactly where they would have met: a column on
the chat row, named for the thing that is not the chat.
So the whole feature is Chronicle now -- `press.mantra.compose.nostr.chronicle`,
`ChronicleEvent` (30327), `ChronicleRequestEvent` (30328), the three tags,
`ChronicleManager`, `docs/member-chronicle.md`. The kind numbers do not move;
only the words do.
**The wire tags move too**, `archiveId` -> `chronicleId` and `archivePage` ->
`chroniclePage`, which is free exactly once. Both kinds are new and there is no
old build to stay compatible with -- the design note says so in as many words --
so the alternative was carrying the old spelling on the wire forever to save a
rename that costs nothing today. The recipient tag stays `p`; it was never ours.
**Schema v14, because two things had the old word written into stored data.**
`ChatRoom.archiveRequestedAt` becomes `chronicleRequestedAt`, renamed rather than
dropped and re-added: while it is set it is the only record that a device with an
empty room has already asked the group for its history, and a device that lost it
mid-flight would ask again on its next launch, and the one after that.
The three `ChatMessage.messageType` strings become their `chronicle*` spellings,
rewritten rather than left to a legacy constant the way `dkgApprovalNeeded` was.
These lines cannot be regenerated -- a chronicle is announced once, when it is
requested, sent and applied -- and an unrecognised type is not skipped by the
transcript. It renders as an ordinary chat bubble, so "Caught up on 12 items"
would come back attributed to a member as something they said.
`MIGRATION_13_14` does both, because Room can rename a column and cannot rewrite
rows in the same breath. `ALTER TABLE ... RENAME COLUMN` needs SQLite 3.25, which
`getRoomDatabase` guarantees by pinning `BundledSQLiteDriver`, and the column is
in no index, no foreign key, and there is not a view or trigger in the database
-- so nothing has to move with it. Five tests hold the two halves apart: the
value survives, the column keeps its position, a room that never asked still
reads as never having asked, the three types are rewritten, and every other type
is left alone.
**`isArchivable` is `isChroniclable`**, on the "recyclable" pattern, and it keeps
its job unchanged: the allowlist that stands between a replayed
`GroupKeyStateEvent` and the apply path.
No behaviour change beyond the rename. 797 tests pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 16:27:36 +02:00
| [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 |
docs: write down how a direct message travels, and what it costs
The reasoning behind this is not recoverable from the code, which is the
bar docs/README.md sets for having a document at all. Three things in
particular would otherwise have to be rediscovered by whoever changes this
next, and two of them are traps.
Why the wrap uses a throwaway key rather than the sender's own -- and what
that does not buy. It does not hide the sender from the group: MLS
authenticates every application message to a leaf, so the identity is
there regardless. What it costs is a carve-out in MIP-03's pubkey check
and the sender's ability to ever read their own messages back.
Why the check that carve-out removes is not a hole. The authorship claim
moves from the wrap's plaintext pubkey to the seal's verified signature,
bound to the MLS leaf that sent it -- strictly harder to forge than what
it replaced.
The one query that would broadcast one of these. What this builds is a
genuine, correctly signed NIP-59 gift wrap, indistinguishable from what
the NIP-17 path would be right to publish, and the only thing keeping it
off a relay is that it never becomes a GiftWrapPayload.
Written against what shipped rather than what was planned, so it records
two deviations. senderIdentity is resolved in NostrDao rather than added
to GroupEventResult.ApplicationMessage, because quartz is a binary
dependency here and the local checkout is a reference copy, not a build
input. And a failed validation drops the message and logs rather than
throwing, because the caller is inside storeNostrEvent's transaction.
The unbuilt parts are listed as absences rather than left implied: there
is no member picker, so a private message can only be a reply to one
somebody already sent, and nothing in the UI yet tells a user in words
that the group can see who they messaged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 19:10:22 +02:00
| [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 |
fix: keep a room's MlsGroup alive so a late message can still be read
Two events published in the same second reliably lose one of them. The
receiver stores the kind:445 and produces nothing from it -- no inner
event, no chat line, no error anybody sees, because MarmotGroupEvent is
written before the message is decrypted and so survives while everything
downstream silently does not.
Observed as a FROST signing session that never started on the receiver:
proposeSigning publishes the proposal and then the proposer's own nonce,
the relay handed them back in the other order, and the proposal was
dropped. The nonce is still sitting there filed against a session that
will never exist. The same bug ate a dialect earlier, which then took out
the artifact referencing it via a foreign key.
MLS is specified to tolerate this. RFC 9420 says a receiver that gets
generation N+1 before N keeps the intermediate keys so the older message
can still be read, and quartz's SecretTree does exactly that, in a
private skippedKeys map. What it does not do is persist it:
exportSenderStates() returns the ratchet positions only, so saveState()
drops the cache. NostrDao rebuilt the group from stored state for every
inbound event, so the cache was empty every single time, and generation N
arriving after N+1 failed `require(generation >= applicationGeneration)`
and was swallowed. Terminal -- the key is derived from a ratchet that has
moved past it, and nothing asks the sender to resend.
This keeps the instance alive instead. MlsGroupCache holds one MlsGroup
per room, and the inbound path goes through it, so skippedKeys survives
from one message to the next. That covers the case that actually bites --
a burst arriving in one sync, decrypted one after another against the
same tree -- which is what every bursty flow needs: proposeRitual sends
two, addArtifact sends two, and addChapter sends one per paragraph plus
one, of which only the ones arriving in ascending generation order
survived.
Reuse is conditional on the stored state still being exactly what the
cache last wrote. Sending a message advances the sender ratchet and saves;
so does adding a member. When that happens the cache rebuilds rather than
carrying on from a group that has been overtaken -- which is what keeps
this from being worse than no cache at all: the fallback is always the old
behaviour, never a diverged ratchet.
One lock per room, not one overall, because the group is mutable and
decryption advances it: two events for the same room decrypted at once
would corrupt the tree, and a busy room should not hold up a quiet one.
**This is a mitigation, not the fix.** It does not survive a restart, and
it does not survive another writer, so a long enough reorder still loses
the message. The fix belongs in quartz -- carry skippedKeys through
saveState/restore -- and quartz is a mavenCentral binary, not a fork, so
it cannot be made here. docs/mls-skipped-keys.md has the analysis, the
patch, the migration constraint on the persisted state format, and the
three ways to actually land it.
Not verified end to end: the proposal that exposed this cannot be
recovered, since its generation is already past, so confirming the fix
needs a fresh burst.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 23:09:53 +02:00
| [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 |
docs: rewrite the sync note as what exists rather than what to build
The design landed across the six commits before this one, so the note is now
describing code. Reorganised around that: the reasoning that made it worth
writing is unchanged, but "the shape to build" is now "how it holds together"
and points at the classes, and the numbered traps have become properties of the
thing rather than warnings about a thing that did not exist yet.
Three sections earn their place after the fact:
- the two timestamp decisions, which are the ones most likely to be "cleaned
up" by someone who has not read this: no `since` on kind 1059 because our
own wraps are stamped up to two days in the past, and no watermark on 445
even though it would be safe, because `limit` already bounds the burst.
- the four ways a group id can appear, which is why the group filter is
derived from the room list rather than wired at the join sites.
- "Not done", which was previously implicit in a staging plan: connectivity
changes, NIP-42 AUTH, the collector-per-socket router the design originally
called for, and the fact that the DM relay set is one relay.
The "suggested order" section is gone; git log is a better record of it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 16:20:08 +02:00
| [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 |
docs: inventory the unreferenced code in the sync and relay stack
Found while building the long-running sync. One item was orphaned by that
change; the rest was already dead and only became visible because the subsystem
was being read closely. Written down rather than deleted because several pieces
are one decision away from being wanted, and those decisions are not the sync
change's to make.
Every claim is "this identifier appears exactly once in composeApp/src, at its
own declaration", with the two things that method cannot see called out: Room
DAO methods are reached through generated code, and Compose entry points can be
invoked without a textual reference. The DAO cluster is flagged as the least
certain for exactly that reason.
Three findings are more than leftovers:
- RelaysSocketManager.userRelays is a field nothing ever writes. The
`userRelays` inside observeRelays is a different, shadowing local, so the
single-argument publishEvent always takes its FALLBACK_RELAYS branch and the
user's own relay list is never used for publishing. That is a bug wearing
dead code's clothes, and the fix is to populate the field, not to delete it.
- NostrPublisherRepository is entirely unreferenced, and it is the only
consumer of CachingImportRepository.importEvents. RelayPool and
RelaysSocketManager each take a cachingImportRepository parameter they store
and never dereference, satisfied by NO_OP_CACHING_IMPORT_REPOSITORY — so the
whole seam is a parameter passed from nowhere to nothing. Removing the
publisher lets the interface and both parameters go with it.
- sendAUTH is unused because NIP-42 is unimplemented, not because it is
surplus. AuthMessage is parsed and dropped, so a relay answering CLOSED with
auth-required is retried forever and can never succeed. Deleting sendAUTH
means deciding against authenticated relays; that is worth doing on purpose
or not at all. sendCOUNT and CountMessage are a similar matched pair — both
go or neither, since a CountMessage cannot arrive if nothing sends a COUNT.
isRecommendedRelay on the two request entities is separated out as its own risk
class: never written, never read, but a Room column, so it wants a migration
rather than a delete.
Ends with an order to do it in, cheapest and least risky first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 16:28:21 +02:00
| [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 |
Merge branch 'mantra' into claude/room-db-testing-setup-b053cd
Brings the branch up to date with the 40 commits mantra gained while the
jvm target was being built, so that merging the other way is a
fast-forward.
One conflict, in docs/README.md, where both sides added rows to the index
table. Kept both, and gave the jvm-target note a clause in the closing
prose since it is the one document there that is not about the protocol.
One thing the auto-merge could not have caught. `9250991` added
NostrEventDao.getMarmotGroupNostrEventsByChatRoomId as a blocking query,
which android accepts and which Room refuses to generate for any other
target -- so the merged tree failed :composeApp:compileKotlinJvm with the
same "Only suspend functions are allowed in DAOs declared in source sets
targeting non-Android platforms" that phase 4 dealt with 58 times. Made
suspend; its only caller, NostrDao.reindexMarmotGroupEvents, was already
suspend, so again no cascade.
That is now a standing cost of this branch rather than a one-off: any DAO
method added on mantra while this is outstanding will break the jvm build
on merge. It is a one-word fix each time, and the compiler names the line.
Verified on the merged tree: :composeApp:compileKotlinJvm and
:composeApp:compileDebugKotlinAndroid green,
:composeApp:testDebugUnitTest 208 passing, :composeApp:jvmTest 214
passing -- both test tasks re-run from scratch rather than taken from the
cache.
The jvm figure is larger than the android one because jvmTest inherits
commonTest, so declaring the target quietly gained the whole shared suite
a second execution environment. That is worth knowing independently of
whether desktop ever ships: the same tests now run on the host, without an
emulator.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 02:01:35 +02:00
| [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 |
docs: measure the UI against the M3 foundations, and phase the work that follows
A plan, not a change: what m3.material.io/foundations asks for as of its May 2026
revision, what these 43 screens actually do, and eight phases ordered so that each
one makes the next mechanical rather than judgemental.
**The spec was read, not remembered.** m3.material.io is a client-rendered SPA --
WebFetch returns an empty `<main>` and the tab URLs 404 on direct navigation -- so
the numbers here came out of a real browser session clicking through the tab
controls. That mattered: the May 2026 revision renamed window size classes to
**breakpoints** and there are now five of them rather than three (compact / medium
/ expanded / large / extra-large, at 600 / 840 / 1200 / 1600dp), renamed responsive
design to adaptive design, and published the spacing system as tokens on an 8dp
scale where `space100 = 8dp`. Writing this from memory of older M3 would have
produced a plan against a vocabulary the current spec no longer uses.
**The palette is fine; the call sites are not.** Every `onX`-on-`X` pair in all six
declared schemes clears 4.5:1, the tightest being `onPrimaryContainer` on
`primaryContainer` at 4.61:1 light and 4.56:1 dark. So the generated scheme is not
the problem and this plan does not propose a repalette. What fails is colour
decided locally, seven pairings of it, and the worst is not visible to a reviewer:
Card(colors = CardDefaults.cardColors(containerColor = primaryContainer)) {
ListItem(colors = ListItemDefaults.colors(containerColor = Color.Transparent),
`cardColors(containerColor = ...)` does derive `contentColor = contentColorFor(...)`,
so `LocalContentColor` inside the card is correct. But `ListItem` does not read
`LocalContentColor` -- its headline comes from `ListTokens.ItemLabelTextColor`,
which is `onSurface` -- and the call site overrides only `containerColor`. In the
light scheme `onSurface` and `primaryContainer` are both `#1B1B1B`. That is
**1.00:1**, and it is applied exactly to `proposal.awaitsYou`, so the proposals
waiting on your signature are the ones rendered invisible. `HomeScreen`'s
`titleContentColor = primary` on `containerColor = primaryContainer` is the same
mistake at 1.22:1. Ratios were computed rather than eyeballed; the script is in the
Phase 0 deliverable.
**Twelve colour roles fall through to Material baseline lavender.** `Color.kt`
never assigns `primaryFixed`, `primaryFixedDim`, `onPrimaryFixed`,
`onPrimaryFixedVariant` or the secondary/tertiary equivalents, so
`lightColorScheme()` defaults them to `ColorLightTokens.PrimaryFixed` ->
`PaletteTokens.Primary90` -> `#EADDFF`. Nothing reads them today, which is why it
has never been noticed; the trap springs the first time an expressive component
does. Read out of the pinned `material3-desktop-1.10.0-alpha05-sources.jar` rather
than assumed.
**Four of the six declared schemes are unreachable.** The medium- and high-contrast
variants are written out in full in `Color.kt` -- 78 colour values -- wired into
`lightColorScheme`/`darkColorScheme` in `Theme.kt`, and then never selected:
`TorchTheme` chooses between `darkScheme` and `lightScheme` only. The work to
honour a platform contrast setting is already done and disconnected.
**10dp and 20dp are not the problem they look like.** They are the two dominant
spacing values (132 and 115 uses) and both are *on* the M3 scale, as `space125` and
`space250`. The plan says so rather than proposing a sweep that would change
nothing. What is wrong is that none of the 520 `.dp` literals records whether it is
padding, a gap or a margin -- the three categories the spec gives different rules
to -- so nothing can be adapted per breakpoint later. About 101 are off-scale
(50dp x 53, 15dp x 14, 5dp x 10 and so on), and `Modifier.height(50.dp)` appears 49
times as the same copied spacer above the same copied error message.
**Findings that were measured and then dropped.** `outlineVariant` reads 1.61:1
against surface and `secondaryContainer` 1.65:1, both of which look alarming and
neither of which is a defect: M3's own baseline sits in the same range, and the 3:1
rule the spec gives is for clustered interactive containers, not dividers or tonal
surfaces. `onSurface.copy(alpha = 0.38f)` is the specified disabled opacity and the
spec exempts disabled states from contrast entirely. Reporting these would have
padded the count and cost the reader trust in the rest.
**The rest of the audit, in counts.** 334 string literals in composables against 2
`stringResource` calls, with title case throughout ("Edit Profile", "New Chat") where
the style guide asks for sentence case. Zero `Snackbar` across 26 `Scaffold`s. 16
copies of `Text("Something went wrong")`, none of which offers a retry. 90 of 240
typography reads on `label*` roles, which are for component text, while `display*`
and `headline*` carry 9 uses between them across 43 screens. 33 bare
`Modifier.clickable` with no minimum target, two of them text-height. Two
`BoxWithConstraints` and no window-size handling at all, on a project with a desktop
target whose own entry point already says so in a comment.
**Eight phases, ordered by what each unblocks.** 0 baseline harness, 1 theme,
2 spacing tokens, 3 accessibility floor, 4 content, 5 states and feedback,
6 adaptive layout, 7 motion, 8 guard rails. Tokens come before the call sites that
consume them; the accessibility floor comes before the adaptive work that would
otherwise double the surface to fix; guard rails come last so they lock in real
state rather than aspiration. Phase 6 is the only one that cannot be done
mechanically and the only one marked not reversible alone.
**What it deliberately does not decide.** Whether the target is
`MaterialExpressiveTheme` or `MaterialTheme` -- the pinned material3 ships the full
expressive set and the code already opts into `ExperimentalMaterial3ExpressiveApi`
in 66 places, but it changes default component shapes and sizes app-wide, so it is a
product call and Phase 1 raises it rather than answering it. Also out of scope:
whether the monochrome palette is right, the per-component specs, iOS (which only
builds on a mac, and whose HIG asks 44dp where M3 asks 48dp), and the three package
namespaces the UI currently lives across.
No code changes. `docs/README.md` gains the row and the closing paragraph's note on
how this one relates to the others.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 23:44:32 +02:00
| [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 |
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
Merge branch 'mantra' into claude/long-running-chat-sync-8983dc
mantra had moved on ~30 commits, several of them in exactly this area — and it
turns out both branches independently found the same bug and drew the same
conclusion about the same filter.
**The overlap.** f38a5f1 fixed the three kind:1059 filters that named the wrong
pubkey, including the two `authors=[userPublicKey]` requests in NostrDao that
could never match a wrap signed by a throwaway key. This branch deleted those
same two blocks, inverting the same `if` to the `== null` case, for the same
reason. The code merged to the same shape; only the comments conflicted, and
they are combined.
**Nip17Filters wins, and the live subscription now defers to it.** ad3304a
extracted the inbox filter to one definition precisely because it had been wrong
in three call sites, with the no-`since` reasoning this branch arrived at
separately. Keeping a fourth copy inside LiveSubscriptionManager would recreate
the problem that commit exists to solve, so:
- queueCatchUpSynchronization now calls Nip17Filters.inbox() instead of
building an identical SynchronizationFilter with its own limit constant,
- Nip17Filters gains liveInbox(), the same shape as a quartz Filter for a REQ
rather than a SynchronizationFilter for the queue, and giftWrapFilter()
defers to it.
Two types for one filter is not duplication worth removing — the queue stores
one and hashes it for computeId, a live subscription puts the other on the wire
— but they belong side by side, because drift here means one of them quietly
stops matching mail.
**ChatMessageListViewModel keeps this branch's resolution.** mantra had it
refresh our own inbox on open (Nip17Filters.inbox on our DM relays, purpose
"chat"); this branch removed that call entirely. Both were right when written,
and the merge is where the second becomes true: LiveSubscriptionManager holds
exactly that filter open on exactly those relays for the whole account and
reconciles it on every foreground, so opening a chat has nothing left to ask
for. The redundancy is now recorded in the comment where the branch used to be,
so it reads as superseded rather than dropped. Discovery — the kind-10050 lookup
for a participant we cannot yet address — is untouched, and the purpose is no
longer a conditional now that only one case reaches it.
The commonTest coroutines-test dependency arrived on both sides; the comment
gives both reasons.
Verified: 154 tests pass, both branches' suites included — Nip17FiltersTest and
the marmot direct-message suites alongside this branch's 46.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 23:58:40 +02:00
Start with the ceremony if you are new to this area; the Marmot notes all assume it.
fix: keep a room's MlsGroup alive so a late message can still be read
Two events published in the same second reliably lose one of them. The
receiver stores the kind:445 and produces nothing from it -- no inner
event, no chat line, no error anybody sees, because MarmotGroupEvent is
written before the message is decrypted and so survives while everything
downstream silently does not.
Observed as a FROST signing session that never started on the receiver:
proposeSigning publishes the proposal and then the proposer's own nonce,
the relay handed them back in the other order, and the proposal was
dropped. The nonce is still sitting there filed against a session that
will never exist. The same bug ate a dialect earlier, which then took out
the artifact referencing it via a foreign key.
MLS is specified to tolerate this. RFC 9420 says a receiver that gets
generation N+1 before N keeps the intermediate keys so the older message
can still be read, and quartz's SecretTree does exactly that, in a
private skippedKeys map. What it does not do is persist it:
exportSenderStates() returns the ratchet positions only, so saveState()
drops the cache. NostrDao rebuilt the group from stored state for every
inbound event, so the cache was empty every single time, and generation N
arriving after N+1 failed `require(generation >= applicationGeneration)`
and was swallowed. Terminal -- the key is derived from a ratchet that has
moved past it, and nothing asks the sender to resend.
This keeps the instance alive instead. MlsGroupCache holds one MlsGroup
per room, and the inbound path goes through it, so skippedKeys survives
from one message to the next. That covers the case that actually bites --
a burst arriving in one sync, decrypted one after another against the
same tree -- which is what every bursty flow needs: proposeRitual sends
two, addArtifact sends two, and addChapter sends one per paragraph plus
one, of which only the ones arriving in ascending generation order
survived.
Reuse is conditional on the stored state still being exactly what the
cache last wrote. Sending a message advances the sender ratchet and saves;
so does adding a member. When that happens the cache rebuilds rather than
carrying on from a group that has been overtaken -- which is what keeps
this from being worse than no cache at all: the fallback is always the old
behaviour, never a diverged ratchet.
One lock per room, not one overall, because the group is mutable and
decryption advances it: two events for the same room decrypted at once
would corrupt the tree, and a busy room should not hold up a quiet one.
**This is a mitigation, not the fix.** It does not survive a restart, and
it does not survive another writer, so a long enough reorder still loses
the message. The fix belongs in quartz -- carry skippedKeys through
saveState/restore -- and quartz is a mavenCentral binary, not a fork, so
it cannot be made here. docs/mls-skipped-keys.md has the analysis, the
patch, the migration constraint on the persisted state format, and the
three ways to actually land it.
Not verified end to end: the proposal that exposed this cannot be
recovered, since its generation is already past, so confirming the fix
needs a fresh burst.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 23:09:53 +02:00
Read the skipped-keys note before debugging any "the other device never got it"
Merge branch 'mantra' into claude/long-running-chat-sync-8983dc
mantra had moved on ~30 commits, several of them in exactly this area — and it
turns out both branches independently found the same bug and drew the same
conclusion about the same filter.
**The overlap.** f38a5f1 fixed the three kind:1059 filters that named the wrong
pubkey, including the two `authors=[userPublicKey]` requests in NostrDao that
could never match a wrap signed by a throwaway key. This branch deleted those
same two blocks, inverting the same `if` to the `== null` case, for the same
reason. The code merged to the same shape; only the comments conflicted, and
they are combined.
**Nip17Filters wins, and the live subscription now defers to it.** ad3304a
extracted the inbox filter to one definition precisely because it had been wrong
in three call sites, with the no-`since` reasoning this branch arrived at
separately. Keeping a fourth copy inside LiveSubscriptionManager would recreate
the problem that commit exists to solve, so:
- queueCatchUpSynchronization now calls Nip17Filters.inbox() instead of
building an identical SynchronizationFilter with its own limit constant,
- Nip17Filters gains liveInbox(), the same shape as a quartz Filter for a REQ
rather than a SynchronizationFilter for the queue, and giftWrapFilter()
defers to it.
Two types for one filter is not duplication worth removing — the queue stores
one and hashes it for computeId, a live subscription puts the other on the wire
— but they belong side by side, because drift here means one of them quietly
stops matching mail.
**ChatMessageListViewModel keeps this branch's resolution.** mantra had it
refresh our own inbox on open (Nip17Filters.inbox on our DM relays, purpose
"chat"); this branch removed that call entirely. Both were right when written,
and the merge is where the second becomes true: LiveSubscriptionManager holds
exactly that filter open on exactly those relays for the whole account and
reconciles it on every foreground, so opening a chat has nothing left to ask
for. The redundancy is now recorded in the comment where the branch used to be,
so it reads as superseded rather than dropped. Discovery — the kind-10050 lookup
for a participant we cannot yet address — is untouched, and the purpose is no
longer a conditional now that only one case reaches it.
The commonTest coroutines-test dependency arrived on both sides; the comment
gives both reasons.
Verified: 154 tests pass, both branches' suites included — Nip17FiltersTest and
the marmot direct-message suites alongside this branch's 46.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-05 23:58:40 +02:00
report — it is silent, and it looks like every other kind of delivery failure. The
Merge branch 'mantra' into claude/room-db-testing-setup-b053cd
Brings the branch up to date with the 40 commits mantra gained while the
jvm target was being built, so that merging the other way is a
fast-forward.
One conflict, in docs/README.md, where both sides added rows to the index
table. Kept both, and gave the jvm-target note a clause in the closing
prose since it is the one document there that is not about the protocol.
One thing the auto-merge could not have caught. `9250991` added
NostrEventDao.getMarmotGroupNostrEventsByChatRoomId as a blocking query,
which android accepts and which Room refuses to generate for any other
target -- so the merged tree failed :composeApp:compileKotlinJvm with the
same "Only suspend functions are allowed in DAOs declared in source sets
targeting non-Android platforms" that phase 4 dealt with 58 times. Made
suspend; its only caller, NostrDao.reindexMarmotGroupEvents, was already
suspend, so again no cascade.
That is now a standing cost of this branch rather than a one-off: any DAO
method added on mantra while this is outstanding will break the jvm build
on merge. It is a one-word fix each time, and the compiler names the line.
Verified on the merged tree: :composeApp:compileKotlinJvm and
:composeApp:compileDebugKotlinAndroid green,
:composeApp:testDebugUnitTest 208 passing, :composeApp:jvmTest 214
passing -- both test tasks re-run from scratch rather than taken from the
cache.
The jvm figure is larger than the android one because jvmTest inherits
commonTest, so declaring the target quietly gained the whole shared suite
a second execution environment. That is worth knowing independently of
whether desktop ever ships: the same tests now run on the host, without an
emulator.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 02:01:35 +02:00
sync note stands alone, and the dead-code inventory reads as a follow-up to it. The
docs(frost): record batch signing as built, and what rollout needs
Phase 7 of docs/frost-batch-signing.md, which is the phase with no code in it.
Nothing needs a feature flag. k=1 is the entire behaviour of the app as shipped
-- no caller batches anything yet -- and at k=1 every message is byte-identical
to the app before Phase 1: encodeProposal returns the bare event object,
joinPayload of one value is that value, and every plural branch in the
transcript is only taken above one. The doc now tabulates that rather than
asserting it in prose, since it is the claim the whole rollout rests on.
The one rollout constraint stands: before a caller batches, the group has to be
on a build that understands array proposals. There is no negotiation for it and
adding one is not worth it -- an old device refuses an array proposal outright,
so the failure mode is a batch that never reaches threshold and is abandoned,
visible in the transcript and costing a retry.
Also records what is left, which is nothing in the protocol: deciding what to
batch is a product question, bounded only by "a batch is only as available as
its worst item" and "GroupKeyStateManager.propose must never batch".
The phases are kept as written rather than rewritten into a description of the
result -- the code reads better against the argument it came from -- with the
two places the implementation chose differently (itemIndex over index,
DROP COLUMN over a table rebuild) marked in their own sections.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 05:00:21 +02:00
batch-signing note is a phased plan that has been built: read it after the
docs: plan handing a new member the group's signed history
A member added after the work was done sees none of it, and nothing in the app
will ever show it to them. Two independent reasons, and the second is the one
that surprises people.
MLS gives no history: a Welcome carries the ratchet tree at the current epoch,
not the transcript, and `MarmotInboundManager` drops anything from an epoch it
holds no keys for. That is forward secrecy working rather than a gap to close.
But group-signed events never travel at all. `FrostSigningManager.complete` says
so in as many words -- a signed event authored by the threshold key cannot go out
as an inner event, because the outbound pipeline would re-author it as its sender
and strip the group's signature off -- so every device *derives* the finished
event from its own `FrostSigningItem` rows. A member who was not in the session
has no items, and no later message carries the event. So the second problem does
not follow from the first and is not fixed by fixing it: even a member who could
decrypt the whole back-transcript would still hold nothing an artifact, chapter
or chunk could be built from.
Which makes an archive not a convenience but the only path, and fixes the line
the design has to hold: **it carries what the group signed, never the chat.**
Restoring the chat would undo forward secrecy on purpose, and a signed event is
the only thing a new member can check for themselves.
**The property the whole plan rests on is already true.** A room's id *is* the
group's threshold key derived at the room's path -- `GroupKeyState.verifies` and
`FrostSigningManager.signingPath` hold that invariant from their own ends -- so
`isSignedByGroup`'s three checks collapse to `event.pubKey == chatRoomId`, an id
check and a signature verify. No key state row, no threshold key, no path, no
lookup. A member who can name the room can verify its signatures, which is
exactly the position a new member is in, and it means the sender of an archive
does not have to be trusted at all.
**Two guards the plan makes non-negotiable.** Nothing on the inbound nip30303
path verifies a signature today, and that is currently correct: rumors carry an
empty sig and are authenticated by the MLS frame, so nothing on the wire has ever
claimed group authorship. An archive is the first thing that does, so the verify
is the feature's entire security rather than hardening on top of it.
And verification turns "group-signed" into an admission ticket for the apply
path, which is a wider door than it looks: a `GroupKeyStateEvent` is group-signed
and would pass perfectly, so an archive could replay a genuine old one and
re-point what the room signs with. The archive therefore carries an allowlist of
document kinds, checked outbound and independently inbound -- the same shape, and
the same reasoning, as the cap on `k` in frost-batch-signing.md.
**Push and pull, in that order of appearance and the reverse order of
importance.** Pushing an archive after the Welcome is what the question asked
for, and on its own it fails the way marmot-membership.md describes: it is an
application message in the epoch the add created, so one that beats the Welcome
there is dropped rather than deferred, silently, while the inviter sees a
success. So the joiner asks instead -- a request is proof it has processed its
Welcome, and it covers the reinstall and the second device, which no invite-time
push can. The push stays as a latency optimisation, deliberately phased after the
thing that makes it safe.
Nine phases: the verifier, the events, assembling an archive, applying one and
the sweep that lets pages arrive out of order, the request, the push, UI, the
cross-device tests, and rollout. The sweep needs no new table -- the inbound path
already stores every inner event it decrypts, so it is the shape
`FrostSigningManager.replayStoredMessages` already has.
Also written down, because it is the first thing this will be reported as a bug
for: an archive lets a new member *read* everything and does not let them sign
anything. `proposeSigningBatch` wants a secret share and a place in the ceremony,
and a group that re-runs its ceremony derives a different room rather than
re-keying this one. Closing that needs share resharing, which is a great deal
more work than this and is the thing to build after it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 13:52:33 +02:00
derivation note, whose one rule is the same one it is built around. The member
refactor: call it a chronicle, and keep "archive" for what a user does to a chat
Archiving a chat is an ordinary thing a user will want to do to a conversation,
and it is not this. This is the group's signed record, handed to a member who
joined after the work was done so their room stops being empty. Two unrelated
meanings of one word in one app is a bug waiting to be written, and
`ChatRoom.archiveRequestedAt` is exactly where they would have met: a column on
the chat row, named for the thing that is not the chat.
So the whole feature is Chronicle now -- `press.mantra.compose.nostr.chronicle`,
`ChronicleEvent` (30327), `ChronicleRequestEvent` (30328), the three tags,
`ChronicleManager`, `docs/member-chronicle.md`. The kind numbers do not move;
only the words do.
**The wire tags move too**, `archiveId` -> `chronicleId` and `archivePage` ->
`chroniclePage`, which is free exactly once. Both kinds are new and there is no
old build to stay compatible with -- the design note says so in as many words --
so the alternative was carrying the old spelling on the wire forever to save a
rename that costs nothing today. The recipient tag stays `p`; it was never ours.
**Schema v14, because two things had the old word written into stored data.**
`ChatRoom.archiveRequestedAt` becomes `chronicleRequestedAt`, renamed rather than
dropped and re-added: while it is set it is the only record that a device with an
empty room has already asked the group for its history, and a device that lost it
mid-flight would ask again on its next launch, and the one after that.
The three `ChatMessage.messageType` strings become their `chronicle*` spellings,
rewritten rather than left to a legacy constant the way `dkgApprovalNeeded` was.
These lines cannot be regenerated -- a chronicle is announced once, when it is
requested, sent and applied -- and an unrecognised type is not skipped by the
transcript. It renders as an ordinary chat bubble, so "Caught up on 12 items"
would come back attributed to a member as something they said.
`MIGRATION_13_14` does both, because Room can rename a column and cannot rewrite
rows in the same breath. `ALTER TABLE ... RENAME COLUMN` needs SQLite 3.25, which
`getRoomDatabase` guarantees by pinning `BundledSQLiteDriver`, and the column is
in no index, no foreign key, and there is not a view or trigger in the database
-- so nothing has to move with it. Five tests hold the two halves apart: the
value survives, the column keeps its position, a room that never asked still
reads as never having asked, the three types are rewritten, and every other type
is left alone.
**`isArchivable` is `isChroniclable`**, on the "recyclable" pattern, and it keeps
its job unchanged: the allowlist that stands between a replayed
`GroupKeyStateEvent` and the apply path.
No behaviour change beyond the rename. 797 tests pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 16:27:36 +02:00
chronicle note is a phased plan that has not been built, and reads as the
docs: plan handing a new member the group's signed history
A member added after the work was done sees none of it, and nothing in the app
will ever show it to them. Two independent reasons, and the second is the one
that surprises people.
MLS gives no history: a Welcome carries the ratchet tree at the current epoch,
not the transcript, and `MarmotInboundManager` drops anything from an epoch it
holds no keys for. That is forward secrecy working rather than a gap to close.
But group-signed events never travel at all. `FrostSigningManager.complete` says
so in as many words -- a signed event authored by the threshold key cannot go out
as an inner event, because the outbound pipeline would re-author it as its sender
and strip the group's signature off -- so every device *derives* the finished
event from its own `FrostSigningItem` rows. A member who was not in the session
has no items, and no later message carries the event. So the second problem does
not follow from the first and is not fixed by fixing it: even a member who could
decrypt the whole back-transcript would still hold nothing an artifact, chapter
or chunk could be built from.
Which makes an archive not a convenience but the only path, and fixes the line
the design has to hold: **it carries what the group signed, never the chat.**
Restoring the chat would undo forward secrecy on purpose, and a signed event is
the only thing a new member can check for themselves.
**The property the whole plan rests on is already true.** A room's id *is* the
group's threshold key derived at the room's path -- `GroupKeyState.verifies` and
`FrostSigningManager.signingPath` hold that invariant from their own ends -- so
`isSignedByGroup`'s three checks collapse to `event.pubKey == chatRoomId`, an id
check and a signature verify. No key state row, no threshold key, no path, no
lookup. A member who can name the room can verify its signatures, which is
exactly the position a new member is in, and it means the sender of an archive
does not have to be trusted at all.
**Two guards the plan makes non-negotiable.** Nothing on the inbound nip30303
path verifies a signature today, and that is currently correct: rumors carry an
empty sig and are authenticated by the MLS frame, so nothing on the wire has ever
claimed group authorship. An archive is the first thing that does, so the verify
is the feature's entire security rather than hardening on top of it.
And verification turns "group-signed" into an admission ticket for the apply
path, which is a wider door than it looks: a `GroupKeyStateEvent` is group-signed
and would pass perfectly, so an archive could replay a genuine old one and
re-point what the room signs with. The archive therefore carries an allowlist of
document kinds, checked outbound and independently inbound -- the same shape, and
the same reasoning, as the cap on `k` in frost-batch-signing.md.
**Push and pull, in that order of appearance and the reverse order of
importance.** Pushing an archive after the Welcome is what the question asked
for, and on its own it fails the way marmot-membership.md describes: it is an
application message in the epoch the add created, so one that beats the Welcome
there is dropped rather than deferred, silently, while the inviter sees a
success. So the joiner asks instead -- a request is proof it has processed its
Welcome, and it covers the reinstall and the second device, which no invite-time
push can. The push stays as a latency optimisation, deliberately phased after the
thing that makes it safe.
Nine phases: the verifier, the events, assembling an archive, applying one and
the sweep that lets pages arrive out of order, the request, the push, UI, the
cross-device tests, and rollout. The sweep needs no new table -- the inbound path
already stores every inner event it decrypts, so it is the shape
`FrostSigningManager.replayStoredMessages` already has.
Also written down, because it is the first thing this will be reported as a bug
for: an archive lets a new member *read* everything and does not let them sign
anything. `proposeSigningBatch` wants a secret share and a place in the ceremony,
and a group that re-runs its ceremony derives a different room rather than
re-keying this one. Closing that needs share resharing, which is a great deal
more work than this and is the thing to build after it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 13:52:33 +02:00
membership note's unanswered half: what a member who joins late can be given,
and the one thing they cannot. The
Merge branch 'mantra' into claude/room-db-testing-setup-b053cd
Brings the branch up to date with the 40 commits mantra gained while the
jvm target was being built, so that merging the other way is a
fast-forward.
One conflict, in docs/README.md, where both sides added rows to the index
table. Kept both, and gave the jvm-target note a clause in the closing
prose since it is the one document there that is not about the protocol.
One thing the auto-merge could not have caught. `9250991` added
NostrEventDao.getMarmotGroupNostrEventsByChatRoomId as a blocking query,
which android accepts and which Room refuses to generate for any other
target -- so the merged tree failed :composeApp:compileKotlinJvm with the
same "Only suspend functions are allowed in DAOs declared in source sets
targeting non-Android platforms" that phase 4 dealt with 58 times. Made
suspend; its only caller, NostrDao.reindexMarmotGroupEvents, was already
suspend, so again no cascade.
That is now a standing cost of this branch rather than a one-off: any DAO
method added on mantra while this is outstanding will break the jvm build
on merge. It is a one-word fix each time, and the compiler names the line.
Verified on the merged tree: :composeApp:compileKotlinJvm and
:composeApp:compileDebugKotlinAndroid green,
:composeApp:testDebugUnitTest 208 passing, :composeApp:jvmTest 214
passing -- both test tasks re-run from scratch rather than taken from the
cache.
The jvm figure is larger than the android one because jvmTest inherits
commonTest, so declaring the target quietly gained the whole shared suite
a second execution environment. That is worth knowing independently of
whether desktop ever ships: the same tests now run on the host, without an
emulator.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-06 02:01:35 +02:00
jvm-target note is unrelated to all of them: it is a build and packaging story.
docs: record what the subgroups plan built, and the six places it chose differently
All nine phases are built, one commit each. The phases are kept as written --
they are the reasoning, and the code reads better against the argument it came
from than against a summary of itself -- with a table of where the building
disagreed with the plan.
Six worth reading. `openCeremony` was never built, because a wrapper over two
repository calls the picker already makes would be a third name for one act.
`MarmotGroupCreation` is reached through the repository rather than called from a
view model, because view models here talk to repositories and managers take the
database. The guards' tests are in jvmTest rather than pure, because every refusal
reads the database and a pure version would test less. Phase 4 added two tags
rather than one, the second fixing a bug older than subgroups -- every robust
group has been arriving nameless on every device but its creator's. `stateFrom`
needed a third reader and a wrapper, because "tag present and unreadable" looks
identical to "absent" through a parser, and "refused" has to be distinguishable
from "none claimed". And Phase 8's two capability refusals short-circuited the
tests already written, which is how it came out that the fixtures had never had a
parent that could sign.
Two the plan got right and worth keeping if this is ever rewritten: the
key-package check moved to the picker on review, before a line was built, and it
is the difference between a subgroup failing in a second and failing after three
ceremonies; and the founding-roster rule has a test whose job is to fail the day
somebody adds the comparison that looks obviously missing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 23:52:19 +02:00
The subgroups note is a phased plan that has been built; it assumes both
docs: plan subgroups, and phase the four ceremonies a group needs to make one
A group can make another group, and the child can prove where it came from. This
is the plan for that, in nine phases, written against the code at b50b1762 and
not yet built.
**A subgroup is an ordinary robust group plus one artefact.** Fresh ChillDKG key,
fresh room, fresh quorum, and a birth certificate -- the parent's signature over
the child's room id -- carried on the child's `GroupKeyState`. Deriving the child
at `m/9420/1/0` instead would cost no ceremony at all and was rejected: a derived
child is the parent wearing a different hat, administered by the parent's members
with the parent's quorum, when the whole point is that a different set of people
can act on their own. The certificate is a claim about lineage, never a
delegation of authority, and nothing here lets one group sign for the other.
**Four steps, in the only order they can happen.** The ceremony produces `K`, so
the child's id exists; the parent's quorum certifies that id; the child's quorum
signs a key state carrying the certificate; the coordinator creates the room. No
step is a policy choice -- each needs the one before it -- and the last is gated
on the key state for the same reason `createAdminGroup` already is.
**What the parent's admins actually sign is the argument that shaped the event.**
Taken literally the certificate is 32 opaque bytes produced by a ceremony most of
them were not in. So the content is exactly the new group id as specified, and
the tags carry the child's threshold key, the path and the admin set -- covered
by the same signature, since an id hashes over its tags -- which lets a signer's
device check `marmotGroupId(key, path) == content` before agreeing, and lets a
coordinator who lies about who is in the child do it in a field the parent's
signature covers.
**The whole certificate travels as JSON on the key state, not a bare signature.**
A signature plus a rule for rebuilding the event it covers is a rule that breaks
silently the first time the event's shape changes: a rebuild differing by one
byte hashes to an id whose signature fails, and is indistinguishable from a
forgery. A parent tag rides beside it as an index into the certificate rather
than a second source of truth -- Phase 3 drops any state carrying one without the
other, or the two disagreeing, so there is no state where the index is believed
and the certificate is not.
**The ceremony stays on gift wraps, and the reason is `mls-skipped-keys.md`.**
Holding all three steps in the parent's Marmot room is the better design and the
plan says so at length rather than dismissing it: the certificate already runs
there, and the key state and the ceremony move together or not at all, since both
`GroupKeyStateManager.propose` and `signingPath` tie a key state to the room its
ceremony ran in. The mechanical cost is three enumerable changes. The reason to
wait is that the skipped-keys note already lists `proposeRitual` as a reliable
trigger, and a DKG cannot finish without every participant -- so one message
dropped for good stalls it permanently, where FROST needs `t` of `n` and routes
around a lost nonce. Revisit when the quartz fix lands; the collision Phase 4
refuses disappears with it.
**Three admins in total, and the threshold is set before anything is published.**
Three is `ChatRoomType.MINIMUM_ROBUST_GROUP_SIZE` for the reason that constant
gives, and the coordinator counts because they hold a share by construction, so
the picker asks for two others. `t` has to be chosen on that same screen and
nowhere later: ChillDKG hashes it and the host keys into the session identity, so
it is fixed the moment the proposal goes out, and a group that disagrees about it
gets no key rather than a weak one.
The nine phases are ordered so the checkable parts come first and can ship dark:
the certificate and its verifier are pure, the schema is three nullable columns,
and nothing produces a certificate until the button in Phase 7 exists. Phase 6
extracts the 120 lines of Marmot room creation out of `DkgRitualViewModel` so
both flows share the rules that are already right there.
What it does not do is named rather than left to be found: no revocation, no
delegation, certificates are not chroniclable, one subgroup per admin set, and
every selected admin has to show up twice.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 22:53:31 +02:00
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.
docs: measure the UI against the M3 foundations, and phase the work that follows
A plan, not a change: what m3.material.io/foundations asks for as of its May 2026
revision, what these 43 screens actually do, and eight phases ordered so that each
one makes the next mechanical rather than judgemental.
**The spec was read, not remembered.** m3.material.io is a client-rendered SPA --
WebFetch returns an empty `<main>` and the tab URLs 404 on direct navigation -- so
the numbers here came out of a real browser session clicking through the tab
controls. That mattered: the May 2026 revision renamed window size classes to
**breakpoints** and there are now five of them rather than three (compact / medium
/ expanded / large / extra-large, at 600 / 840 / 1200 / 1600dp), renamed responsive
design to adaptive design, and published the spacing system as tokens on an 8dp
scale where `space100 = 8dp`. Writing this from memory of older M3 would have
produced a plan against a vocabulary the current spec no longer uses.
**The palette is fine; the call sites are not.** Every `onX`-on-`X` pair in all six
declared schemes clears 4.5:1, the tightest being `onPrimaryContainer` on
`primaryContainer` at 4.61:1 light and 4.56:1 dark. So the generated scheme is not
the problem and this plan does not propose a repalette. What fails is colour
decided locally, seven pairings of it, and the worst is not visible to a reviewer:
Card(colors = CardDefaults.cardColors(containerColor = primaryContainer)) {
ListItem(colors = ListItemDefaults.colors(containerColor = Color.Transparent),
`cardColors(containerColor = ...)` does derive `contentColor = contentColorFor(...)`,
so `LocalContentColor` inside the card is correct. But `ListItem` does not read
`LocalContentColor` -- its headline comes from `ListTokens.ItemLabelTextColor`,
which is `onSurface` -- and the call site overrides only `containerColor`. In the
light scheme `onSurface` and `primaryContainer` are both `#1B1B1B`. That is
**1.00:1**, and it is applied exactly to `proposal.awaitsYou`, so the proposals
waiting on your signature are the ones rendered invisible. `HomeScreen`'s
`titleContentColor = primary` on `containerColor = primaryContainer` is the same
mistake at 1.22:1. Ratios were computed rather than eyeballed; the script is in the
Phase 0 deliverable.
**Twelve colour roles fall through to Material baseline lavender.** `Color.kt`
never assigns `primaryFixed`, `primaryFixedDim`, `onPrimaryFixed`,
`onPrimaryFixedVariant` or the secondary/tertiary equivalents, so
`lightColorScheme()` defaults them to `ColorLightTokens.PrimaryFixed` ->
`PaletteTokens.Primary90` -> `#EADDFF`. Nothing reads them today, which is why it
has never been noticed; the trap springs the first time an expressive component
does. Read out of the pinned `material3-desktop-1.10.0-alpha05-sources.jar` rather
than assumed.
**Four of the six declared schemes are unreachable.** The medium- and high-contrast
variants are written out in full in `Color.kt` -- 78 colour values -- wired into
`lightColorScheme`/`darkColorScheme` in `Theme.kt`, and then never selected:
`TorchTheme` chooses between `darkScheme` and `lightScheme` only. The work to
honour a platform contrast setting is already done and disconnected.
**10dp and 20dp are not the problem they look like.** They are the two dominant
spacing values (132 and 115 uses) and both are *on* the M3 scale, as `space125` and
`space250`. The plan says so rather than proposing a sweep that would change
nothing. What is wrong is that none of the 520 `.dp` literals records whether it is
padding, a gap or a margin -- the three categories the spec gives different rules
to -- so nothing can be adapted per breakpoint later. About 101 are off-scale
(50dp x 53, 15dp x 14, 5dp x 10 and so on), and `Modifier.height(50.dp)` appears 49
times as the same copied spacer above the same copied error message.
**Findings that were measured and then dropped.** `outlineVariant` reads 1.61:1
against surface and `secondaryContainer` 1.65:1, both of which look alarming and
neither of which is a defect: M3's own baseline sits in the same range, and the 3:1
rule the spec gives is for clustered interactive containers, not dividers or tonal
surfaces. `onSurface.copy(alpha = 0.38f)` is the specified disabled opacity and the
spec exempts disabled states from contrast entirely. Reporting these would have
padded the count and cost the reader trust in the rest.
**The rest of the audit, in counts.** 334 string literals in composables against 2
`stringResource` calls, with title case throughout ("Edit Profile", "New Chat") where
the style guide asks for sentence case. Zero `Snackbar` across 26 `Scaffold`s. 16
copies of `Text("Something went wrong")`, none of which offers a retry. 90 of 240
typography reads on `label*` roles, which are for component text, while `display*`
and `headline*` carry 9 uses between them across 43 screens. 33 bare
`Modifier.clickable` with no minimum target, two of them text-height. Two
`BoxWithConstraints` and no window-size handling at all, on a project with a desktop
target whose own entry point already says so in a comment.
**Eight phases, ordered by what each unblocks.** 0 baseline harness, 1 theme,
2 spacing tokens, 3 accessibility floor, 4 content, 5 states and feedback,
6 adaptive layout, 7 motion, 8 guard rails. Tokens come before the call sites that
consume them; the accessibility floor comes before the adaptive work that would
otherwise double the surface to fix; guard rails come last so they lock in real
state rather than aspiration. Phase 6 is the only one that cannot be done
mechanically and the only one marked not reversible alone.
**What it deliberately does not decide.** Whether the target is
`MaterialExpressiveTheme` or `MaterialTheme` -- the pinned material3 ships the full
expressive set and the code already opts into `ExperimentalMaterial3ExpressiveApi`
in 66 places, but it changes default component shapes and sizes app-wide, so it is a
product call and Phase 1 raises it rather than answering it. Also out of scope:
whether the monochrome palette is right, the per-component specs, iOS (which only
builds on a mac, and whose HIG asks 44dp where M3 asks 48dp), and the three package
namespaces the UI currently lives across.
No code changes. `docs/README.md` gains the row and the closing paragraph's note on
how this one relates to the others.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 23:44:32 +02:00
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.
