Upgrade guide
This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.
Scope and provenance
This guide compares v0.16.0 / marmotkit-v0.16.0 / marmotc-v0.16.0 /
wn-agent-v0.16.0, which all peel to
a2e0558a634bbd20607cdd5afb93abc6220ee58d, with the source to be shipped as
v0.17.0. All four 0.17.0 cohort tags must peel to the release PR's merged
commit, and packaged manifests must record that exact SHA. The comparison was
prepared against origin/master at 9cf81ea674a8e6e63f9f899261ee7fe58b529681
(45 commits after v0.16.0); the release commit is this documentation update's
merge on top of it. Use the full release SHA from the tags for artifact
verification. This guide ships in the release commit, not a later supplement.
See the release notes, previous upgrade guide,
and current binding reference.
Readers: native app hosts (Swift/Kotlin through MarmotKit), C hosts, Rust hosts
that embed marmot-app or lower crates, and WN Agent operators.
The largest client change is the create and invite result shape: these calls
now go ahead with the members who are available and report every requested
account's outcome. The v4 whole-file audit upload is removed. MarmotKitError
gains one case (CreatedGroupMemberReportUnavailable), C gains one status
(130), and no MarmotEventFfi case is added. Account databases migrate from
schema 201 to 207. The wire format and conformance vectors are unchanged apart
from their version stamp.
Upgrade decisions
| Category | Required action or effect |
|---|---|
| Required | Replace generated Swift/Kotlin, native libraries and C headers together. Adopt the new create and invite result records. Replace setAuditLogTrackerConfig with setAuditLogSource and remove calls to postAuditLogFile and postAuditLogTrackerUpdate. Handle MarmotKitError.CreatedGroupMemberReportUnavailable. Stop reading AppPerformanceSnapshotFfi.accountGroupReadSnapshot and the removed v4 fields of the v5 tracker result. |
| Required for C hosts | Recompile. Create and invite outputs are new structs with their own free functions; marmot_created_group_free is removed. marmot_set_audit_log_source replaces both tracker-config setters. MarmotAuditLogTrackerUpdateResultV5 and MarmotAppPerformanceSnapshot change layout. See C host changes. |
| Required storage | Allow account migrations 0202 to 0207 (schema 201 → 207) on first open. The shared database is unchanged. Downgrade is unsupported. |
| Required for Rust hosts | Creates and invites return GroupMemberResult<T>; TransportPeeler::peel_group_message takes a PreparedGroupMessage; GroupStorage::put_group is replaced; StorageProvider requires CommittedRosterStorage. See Rust host changes. |
| Required for agent-control clients | None. Creates and invites stay all-or-nothing and fail as before when any requested member is unavailable. |
| New defaults | A group relay's lasting refusal of a confirmed change warns until acknowledged and gates group changes; creates and invites proceed with available members; account and group reads answer from the published read state; no coverage-ledger history notices; broken recovery units probe quietly; four concurrent attachment downloads with on-screen work first; storage-blocked downloads park until space covers them; commits over 64 KiB withheld from relays of unknown limit; sends a relay answered rate-limited: or auth-required: stay pending after a later refusal; deleted failed sends leave the timeline; bare note1/nevent1/naddr1 references become NostrUri; White Noise's new groups drop cdn.hzrd149.com. |
| Optional adoption | discardFailedSend, createTaggedPoll, sendTaggedSticker, stickerPackShareLink, the read_state_publish runtime operation, the native-host test recipe. |
| Automatic fixes | quinn RustSec advisories; repeated history reconstruction from undecryptable envelopes; external-signer archive, forget and delete; foreground sends behind optional-relay retries; NotificationUpdate.isDm; attachment promotion resumes; directory fetch failures during create and invite; double snapshots in rewind windows without savepoints; timeline triggers after withdrawals; one-shot CLI exits. |
Required upgrade steps
-
Pin all MDK, MarmotKit, Marmot C and WN Agent inputs to 0.17.0. Verify the source SHA in each manifest and every sibling checksum. Do not combine new generated records or headers with 0.16.0 native libraries. See the distribution guide.
-
Adopt the create and invite results. See Partial group creates and invites.
Method 0.16.0 returned 0.17.0 returns createGroup,createGroupWithOptions, the initial-image and prepared-image createsString(group id)GroupCreationResultFficreateGroupDetailed,createGroupWithOptionsDetailed,createGroupWithInitialImageDetailedCreatedGroupFfiDetailedGroupCreationResultFfiinviteMembers,inviteMembersWithInitialAdminsSendSummaryFfiInviteMembersResultFfiinviteMembersDetailed,inviteMembersDetailedWithInitialAdminsGroupMutationResultFfiGroupInviteResultFfiOther detailed group mutations keep
GroupMutationResultFfi, andstartDirectConversationkeeps its signature: it stays all-or-nothing. -
Replace the audit source setter.
setAuditLogSource(AuditLogSourceFfi)takes the samehardwareModel,platformandappVersionas the removedAuditLogTrackerConfigV4Ffiminus the upload URL and token, and returns the trimmed stored value (a blank field becomes absent). Call it on every launch before opening accounts: a recorder already open keeps the source it started with. The hardware model must come from system model information, never a device name, hostname or serial number. RemovepostAuditLogFileandpostAuditLogTrackerUpdate; keep callingpostAuditLogTrackerUpdateV5, whoseAuditLogTrackerUpdateResultV5Ffinow holds onlyenabledandv5. Builds no longer embedMARMOT_AUDIT_LOG_TRACKER_ENDPOINT.MarmotServiceEndpointsno longer carries a tracker endpoint. Local v4 files stay listable and deletable until retention expires them, and startup deletes the orphanedaudit-upload-checkpoint.json._ = try kit.setAuditLogSource(source: AuditLogSourceFfi( hardwareModel: systemModelIdentifier(), platform: "ios", appVersion: appVersion))marmot.setAuditLogSource(AuditLogSourceFfi(Build.MODEL, "android", appVersion)) -
Handle
MarmotKitError.CreatedGroupMemberReportUnavailable(groupIdHex:)(KotlinMarmotKitException.CreatedGroupMemberReportUnavailable). A prepared-image create that reuses an upload consumed before this release finds the group that upload created, but no member report was kept for it. Open that group; do not create another. Exhaustive error switches must add the case. -
Remove reads of
AppPerformanceSnapshotFfi.accountGroupReadSnapshot. The startup group-read snapshot it timed no longer exists, because group reads answer from the published read state.accountProfileLoadstays and now times the profile load each member read takes. -
Keep
HistoryNoticeCauseFfi.UnprovenHistoryin exhaustive switches. It is no longer emitted; see History notices.
Storage upgrade
Account databases run six migrations on first open, moving from schema 201 to 207:
| Migration | Change |
|---|---|
| 0202 | Adds relays_json to sticker packs, defaulting existing packs to an empty hint list. |
| 0203 | Adds member_outcomes_json to prepared group-image uploads, so a retried create returns its original member report. |
| 0204 | Drops the timeline rows of own sends that failed and were then deleted. The source rows stay. A deleted failed send with a live peer reaction or a kept receipt is settled as delivered instead (failure cleared, recipient confirmed) and keeps its placeholder. |
| 0205 | Adds attachment_acquisition.storage_readmitted for storage-parked downloads. |
| 0206 | Adds the committed-roster tables and an account-wide roster revision. It seeds nothing: the engine records each group's roster the next time it fully hydrates the group. |
| 0207 | Adds cgka_commit_refusals, the confirmed own commits a group relay refused for good, kept until acknowledged. |
None of these rewrites message history; 0204 deletes only the affected
timeline rows. The shared database (shared.sqlite3) is unchanged. A 0.16.0
binary refuses the upgraded account database before reading or writing its
tables.
Downgrade to 0.16.0 is unsupported. If you may need to roll back, keep a device-local copy of the MDK data directory taken before upgrading while the app and every extension (such as a notification extension) are stopped, so no database or its WAL file is open while it is copied. Never remove migration rows by hand. See the storage-format contract.
Partial group creates and invites
A create or invite used to stop at the first unavailable account. Now directory resolution returns one outcome per requested account, deduplicated and in request order, and the call runs one MLS operation for the available accounts.
GroupCreationResultFfi { groupIdHex: String?, memberOutcomes }DetailedGroupCreationResultFfi { created: CreatedGroupFfi?, memberOutcomes }InviteMembersResultFfi { summary: SendSummaryFfi?, memberOutcomes }GroupInviteResultFfi { invite: InviteMembersResultFfi, details, managementState }MemberResolutionOutcomeFfi { accountIdHex, status, selectedDeviceCount }.statusisselected,missingKeyPackage,obsoleteKeyPackage,invalidKeyPackage,incompatibleKeyPackage,missingInboxRouteorincomplete;selectedDeviceCountis zero for every status butselected.
Read the result in this order:
- If the operation (
groupIdHex,createdorsummary) is absent, nothing changed: a nonempty request found no available member, so no group or commit exists. Show the outcomes. An empty member list still creates a creator-only group. - If it is present, a create's group is canonical locally. An invite's
summarykeeps its 0.16.0 meaning: readsummary.acceptDispositionas before.publishedmeans the commit went out;acceptedPendingmeans the invite is queued while the group settles and can still be refused (QueuedIntentRefused);completionUnknownmeans the commit is unresolved. Keep showing those members as pending until the change settles. In every case, show the accounts that were notselected, for example as "could not be added". selectedmeans MDK found fresh, compatible devices and a safe inbox route. It is not a join or a Welcome delivery: keep usingpendingWelcomeDeliveriesandWelcomeDeliveryPendingfor that.
incomplete means the relay reads for that account did not finish; per-member
recovery still applies. Invalid input, authorization, lifecycle, storage and
directory fetch failures remain errors and are never turned into outcomes.
Initial admins apply only to selected members, in the same commit. A retried
prepared-image create returns the original report, kept across restarts.
let result = try await kit.createGroup(
accountRef: account, name: name, memberRefs: members, description: nil)
let skipped = result.memberOutcomes.filter { $0.status != .selected }
guard let groupIdHex = result.groupIdHex else {
showNobodyAvailable(skipped)
return
}
openChat(groupIdHex)
if !skipped.isEmpty { showNotAdded(skipped) }
val result = marmot.createGroup(account, name, members, null)
val skipped = result.memberOutcomes.filter { it.status != MemberResolutionStatusFfi.SELECTED }
val groupIdHex = result.groupIdHex ?: return showNobodyAvailable(skipped)
openChat(groupIdHex)
if (skipped.isNotEmpty()) showNotAdded(skipped)
Changed defaults
Reads from the published read state
The account worker now publishes an immutable, versioned read state at each quiescent point: before every reply and host event, during catch-up, and when a time-bound answer expires. These reads answer from it on the caller's task, without waiting in the worker's queue:
- account reads: quarantined groups, KeyPackage status and the owned list, maintenance policy and per-group maintenance status, commit delivery, and backup restore status and watch;
- group reads:
groupMembers,groupMemberIdsPage,groupMlsStateand its diagnostic form,groupRoster/groupConversationSnapshot, andgroupAppComponent.
Each answer is what the worker would have given at that publish. Because the
worker publishes before it replies, a read made after a mutation returns sees
that mutation. During startup, a group read that names a group still awaiting
hydration asks the worker to hydrate it and answers once it has: live,
quarantined or gone (UnknownGroup). A forget sent while startup hydration
runs now takes effect at its place in the worker's command order, so a later
read cannot bring the group back. Pending Welcomes and some other reads still
go through the worker queue (see Acceptance and remaining work).
No call changes. If your app works around slow reads during sends or catch-up (spinners, caching, timeouts), revisit those paths.
Relay refusals of confirmed changes
A group relay that refuses one of your confirmed changes for good (too large
for it, or any other final answer) now warns until the user acknowledges it,
and the warning survives restarts. groupCommitDelivery names the oldest
refused change ahead of any owed one and lists refusedRelays, each a
GroupCommitRefusedRelayFfi with relayUrl, cause
(GroupCommitRefusalCauseFfi.TooLarge or Rejected) and sizeClass
(TooLarge only, when known). It returns nil/null only once no relay is
owed a change of yours and every refusal has been acknowledged. MDK will not
deliver the change there, so members who read only that relay may not have
it.
A refusal makes group changes fail with GroupCommitUndelivered at once,
without the two-minute grace. acknowledgeGroupCommitUndelivered now also
dismisses the group's refusals for good, so a "dismiss" action can call it.
A relay the host-safety rule refuses is not reported, and a disbanded group
reports no refusal. If your commit-delivery UI shows only owed relays, add
the refused ones.
Large commits and retryable relay answers
A commit over 64 KiB is not sent to a relay whose event limit MDK does not
know: neither listed in the deployment's relayEventLimits nor advertised by
NIP-11. Such a relay could close its socket on the oversized frame and leave the
commit possibly seen, which kept it pending for good. MDK connects to such a
relay and, once the socket is up, refuses the commit there locally without
sending it; a relay that is slow to connect but connects is refused the same
way. A commit refused at every relay rolls back as too large (EventTooLarge,
or QueuedIntentRefused with event_too_large for a queued change). Only a
relay the device cannot connect to holds the commit for a retry, so an offline
device never gets a false "too large". The White Noise preset lists 2 MiB for its relays, so
its groups are not affected. Custom deployments with large groups should list
their relays' limits.
Exposure is now settled once for every send. A relay that answered
rate-limited: or auth-required: counts as having received the event, so a
later refusal there (invalid:, blocked:) no longer fails or rolls it back:
the send stays pending and keeps retrying, and while no relay has accepted it,
later sends in the group wait behind it, as they do behind a send that timed
out. Expect such a message to stay in its pending state rather than switch to
failed.
History notices
The coverage ledger no longer raises "history may be incomplete" notices. A
notice now needs evidence that messages are missing (an epoch gap the
runner's visits exhausted, a maintenance or known-event park an upgrade kept)
or a rejoin. HistoryNoticeCauseFfi.UnprovenHistory stays in the enum but is
not emitted. Notices shown for it before the upgrade leave the list, and
dismissHistoryNotice with one of their ids returns false and changes
nothing.
A broken recovery unit, such as a relay that refused the runner or could not prove a route's history, probes quietly on a timer instead of waiting for a dismissal: an hour after it breaks, then on an interval that doubles up to a day. A probe follows the runner's ordinary scheduling, budgets and relay cooldowns, raises no notice and never shows as catching up. Units broken before the upgrade probe once right after it. If that probe fails, a unit that broke for lack of progress under 0.16.0 keeps its earlier retry step and usually waits a full day, while one that broke on a relay refusal (such as an inbox relay that refuses NIP-77) or in the coverage-ledger conversion waits an hour and then doubles up to a day. If your UI explained the old notice or offered a dismiss action for it, remove that copy.
Attachment downloads
Downloads run four at a time across a runtime's accounts instead of one, and
each account's media HTTP lane grows from four slots to five so one stays free
for foreground work. While free space cannot cover four transfers at the
largest account limit, they run one at a time. requestAutomaticAttachment on
queued work moves it ahead of other automatic downloads, most recent request
first; call it for what is on screen. Taps still go first.
A download the worker cannot start for lack of free disk now parks as
AttachmentTransferStateFfi.storageBlocked, with what it needs as its target,
instead of retrying every 15 seconds as retryScheduled. It is readmitted once
free space covers it; readmission releases parked downloads in priority order
only while free space funds them together, so the rest stay
storageBlocked. Show a storage prompt for that state, as you already do.
Timeline and Markdown
- A failed own send that the user deletes leaves the timeline instead of staying as a "deleted" row that still reports failure. Migration 0204 drops existing rows of this kind. A deleted failed send with a peer reaction (also one that arrived after the deletion) or a kept receipt is delivered instead: its failure clears and it keeps its placeholder.
- A bare
note1,nevent1ornaddr1reference with a valid bech32 checksum is now aMarkdownInlineFfiNostrUriinstead of text, so copied note ids can render as event cards. An invalid checksum stays text; barenpubmentions and explicitnostr:URIs are unchanged. The reference is not resolved or fetched by the parser. - Poll rows keep their reply target and parent preview, like chat messages.
Deployment
The White Noise preset drops https://cdn.hzrd149.com from new groups' media
endpoints, because it now refuses uploads from unlisted pubkeys. Existing
groups keep their signed endpoint list until an admin replaces it.
Feature adoption
Discarding a failed send (optional)
discardFailedSend(accountRef:groupIdHex:messageIdHex:) removes a failed own
send from this device and publishes nothing. Offer it instead of
deleteMessage on a row whose invalidationStatus is
local_publish_failed: a delete would tell the group about a message nobody
received. It returns DiscardFailedSendResultFfi:
outcome:discarded;stillSendingwhen the group has a send the engine may still publish, which could be this one (nothing changed; try again later); ornotFailedSendfor any row that is not a failed own send.mediaCiphertextSha256: hashes of the send's encrypted media, for purging a decrypted-media cache. Empty unless discarded.erasurePending: the send is gone but secure WAL truncation is still pending; the next secure delete in the group retries it.
The row, its edits and media references are securely deleted, and timeline
subscribers receive the removal with reason Cleared.
let result = try await kit.discardFailedSend(
accountRef: account, groupIdHex: group, messageIdHex: message)
if result.outcome == .discarded { purgeMediaCache(result.mediaCiphertextSha256) }
val result = marmot.discardFailedSend(account, group, message)
if (result.outcome == DiscardFailedSendOutcomeFfi.DISCARDED) purgeMediaCache(result.mediaCiphertextSha256)
Tagged polls and stickers (optional)
createTaggedPoll and sendTaggedSticker take the arguments of createPoll
and sendSticker plus a final messageTags: [[String]] for a reply e,
NIP-22 E/K/P or effect tags on the same event. Poll context must not
contain imeta, option, polltype, endsAt or response, and the poll's
generated tags plus the context must total at most 32. Sticker context cannot
add a second sticker or an imeta. createPoll and sendSticker keep their
signatures. See polls and
stickers.
Sticker pack share links (optional)
stickerPackShareLink(accountRef:coordinate:) builds a canonical Sonar viewer
link locally, with no network work, carrying up to eight retained relay hints.
Newer fetch candidates displace older hints, and the current relay safety
policy filters them. A pack with no usable hint uses the account's relays.
Hints that would exceed the link parser's size limit are left out. Use it
instead of building the URL in the host.
Read-state telemetry (optional)
runtimeOperations in the performance snapshot gains read_state_publish:
the count and duration of each new version of an account's published read
state.
Native-host test recipe (optional)
The native-host test recipe
runs generated Swift against a local MockRelay with injected test-only secret
storage, checking delivery and same-root reopening without production
credentials: bash crates/marmot-uniffi/native-host-smoke.sh. It also gives
the matching Android configuration.
C host changes
Recompile every consumer against the 0.17.0 header and library.
- Create outputs are
MarmotGroupCreationResult(group_id_hexNULL when no group was created) orMarmotDetailedGroupCreationResult(createdNULL likewise); invite outputs areMarmotInviteMembersResult(summaryNULL when nothing changed) orMarmotGroupInviteResult. Each carriesmember_outcomes/member_outcomes_lenofMarmotMemberResolutionOutcome. Free each root withmarmot_group_creation_free,marmot_detailed_creation_free,marmot_invite_members_freeormarmot_group_invite_free, nevermarmot_string_freeormarmot_send_summary_free.marmot_created_group_freeis removed; the created group is embedded in the detailed result. MARMOT_STATUS_CREATED_GROUP_MEMBER_REPORT_UNAVAILABLE(130) is the C form ofCreatedGroupMemberReportUnavailable; open the group the error detail names.marmot_set_audit_log_sourcereplacesmarmot_set_audit_log_tracker_configandmarmot_set_audit_log_tracker_config_v4. It borrows aMarmotAuditLogSource(hardware_model,platform,app_version) and returns a copy freed withmarmot_audit_log_source_free.marmot_post_audit_log_file,marmot_post_audit_log_tracker_update, their result types and frees, and the tracker config types and frees are removed.MarmotAuditLogTrackerUpdateResultV5dropsv4_uploaded,v4_uploaded_lenandv4_skipped_reason.MarmotAppPerformanceSnapshotdropsaccount_group_read_snapshot.MarmotGroupCommitDeliveryappendsrefused_relays/refused_relays_lenaftersince, each aMarmotGroupCommitRefusedRelay(relay_url, aMarmotGroupCommitRefusalCause,has_size_class/size_class), freed bymarmot_group_commit_delivery_free.- New:
marmot_discard_failed_send(free withmarmot_discard_failed_send_result_free);marmot_create_tagged_pollandmarmot_send_tagged_sticker, which borrowMarmotStringArraytag rows;marmot_sticker_pack_share_link, whose string you free withmarmot_string_free. Existing entry points and record layouts for polls and stickers are unchanged.
struct MarmotGroupCreationResult *result = NULL;
MarmotStatus status = marmot_create_group(client, account, name, members, members_len, NULL, &result);
if (status == MARMOT_STATUS_OK) {
if (result->group_id_hex == NULL) { /* nobody available; inspect member_outcomes */ }
marmot_group_creation_free(result);
}
See the C guide and symbol inventory.
Rust host changes
marmot-app:create_group,create_group_detailed,create_group_with_options*, the initial-image creates andinvite_members*returnGroupMemberResult<T>(operation: Option<T>,member_outcomes).invite_members_with_initial_adminstakes aMemberResolutionPolicy, andAppCreateGroupOptionsgainsmember_resolution;Partial, the default, proceeds with available members andAtomickeeps the all-or-nothing behavior, failing with the directory error when any member is unavailable.AppErrorgainsCreatedGroupMemberReportUnavailable.marmot-appaudit:post_audit_log_file,AuditLogUploadResult,AuditLogTrackerConfig,set_audit_log_tracker_configandMarmotServiceEndpoints::audit_log_tracker_endpointare removed. UseMarmotAppRuntime::set_audit_log_source(AuditLogSource).AuditLogTrackerUpdateResultkeeps onlyenabledandv5.marmot-appcommit delivery:GroupCommitDeliverygainsrefused_relays: Vec<GroupCommitRefusedRelay>; struct literals add it.storage-sqlite:list_prepared_group_image_uploadsis replaced bylist_prepared_group_image_upload_statuses(statuses without image data or secrets; useprepared_group_image_upload(upload_id)for one full record), andaccount_group_self_membershipsby the per-groupgroup_standing.marmot-appreads:AppPerformanceSnapshotdropsaccount_group_read_snapshot;MarmotAppConfigdropsdev_force_group_read_snapshot_failureand its builder.marmot-appdownloads: storage-blocked downloads park as described in Attachment downloads.SqliteAppStorage::readmit_storage_blocked_attachmentstakes aneedfunction, andrequest_automatic_attachmentreturns whether the order changed.cgka_traits:TransportPeeler::peel_group_messagetakes&PreparedGroupMessage<'_>. Move context-independent validation and decoding intoprepare_group_message(the default borrows the raw payload); a wrapping peeler delegates preparation to the peeler that decrypts.GroupStorage::put_groupis replaced byput_group_with_roster(group, committed)for writes that merge, clear or re-derive membership andput_group_keeping_roster(group)for every other write.StorageProviderrequiresCommittedRosterStorageand addshas_atomic_group_savepoints,past_peel_context_generationandmls_storage_failure, each with a safe default.cgka_traitstransport:TransportEndpointFailuregainspre_send: bool; struct literals must set it. Set ittrueonly when no frame can have left (a dial refusal, a DNS failure, a socket that never opened, or the adapter refused the event itself); a relay'srate-limited:orauth-required:answer is never pre-send.falsecounts the target as possibly exposed, so a later refusal there no longer rolls back the commit.TransportAdapteraddscommit_size_refusals(default refuses nothing) andpublish_commit(defaultpublish); an adapter that applies the 64 KiB commit floor at relays of unknown limit overrides both.nostr-directory:Directory::resolve_compatible_member_key_packagestakes aMemberResolutionPolicy, andResolvedMemberKeyPackagesgainsmember_outcomes. PassAtomicfor the previous behavior, which fails on the first unavailable member;Partialreturns per-account outcomes.storage-sqlite:RecoveryUnitPolicygainsprobe_base_secondsandprobe_cap_seconds;dismiss_recovery_route_parkanddismiss_recovery_route_park_onare removed.put_groupstays only undertest-support.- Engine, session and runtime add
durably_owned_key_packages_with_validity, anddurably_owned_key_packagesnow fails with the storage error when a stored bundle cannot be read. marmot-forensicsadds three v5 audit kinds (recovery_runner_fetched,recovery_runner_raced,recovery_runner_changed) and their vocabularies.- The
incident-replaycrate is removed.
See the crate changelogs for marmot-app, cgka-engine, cgka-traits and
storage-sqlite.
WN Agent and integrations
The agent-control protocol is unchanged, and creates and invites through it
stay all-or-nothing: the connector uses the atomic policy, so a request with
any unavailable member fails as it did in 0.16.0 (app_error) and nothing is
created or committed. Hermes, OpenClaw and the terminal harnesses need no
change; upgrade them with the connector as usual.
wn CLI: group creation and invites keep eligible members when another
requested member is unavailable. JSON adds member_outcomes with each
account's status and selected device count; creation returns
group_id: null and invites summary: null when no member is eligible. One-shot
commands now shut their runtime down before exiting.
Changes requiring no new calls
quinn-proto0.11.19 andquinn-udp0.5.16 fix RUSTSEC-2026-0523, RUSTSEC-2026-0524 and RUSTSEC-2026-0538.- Live ingest reuses cached historical peel contexts, so correctly signed
envelopes encrypted with an unrelated key no longer make the receiver rebuild
past group state once per envelope
(#2492). This applies to
SQLite storage; a custom provider that keeps the default
past_peel_context_generationofNonestays uncached. - Archive, forget and delete for an external-signer account's chat go through its running worker. Before, the worker's next save of the chat could unarchive it, and after a forget or delete it kept answering for the group.
- A foreground send no longer waits behind a scheduled retry to an optional relay that withholds its acknowledgement.
NotificationUpdate.isDmfollows the chat-list conversation kind for messages, group-state notices and invitations, including pending DM Welcomes.- Outgoing attachment promotion resumes after a skipped batch without waiting for the maintenance tick.
- Create and invite abort on directory fetch failures instead of reporting
recipients as
incompletein a successful result. - On storage without atomic group savepoints, a contained rewind window writes one snapshot, so a crash no longer quarantines the group on the next open. SQLite is unchanged.
- Timeline updates after a withdrawn delete of an edit report
MessageEditedOrReprojectedandReplyPreviewChangedinstead ofReactionAdded, and batch withdrawals attribute each row to an event that changed it. - Every engine OpenMLS load refuses a group whose rewind restore failed. No current path reached that state.
Acceptance and remaining work
Before shipping an app on 0.17.0:
- Compile against the matched artifacts with every exhaustive
switch/whenupdated; for C, rebuild every consumer and check every create and invite free path. - Upgrade a 0.16.0 install in place and confirm the account database migrates once and the second open changes nothing. Confirm 0.16.0 refuses to reopen it, and that restoring the pre-upgrade copy works.
- Create a group and invite members where one member has no KeyPackage, where every member lacks one, and with an empty member list. Confirm the UI shows skipped accounts and treats a missing operation as "nothing changed".
- Confirm
setAuditLogSourceruns on every launch before accounts open, and that v5 audit delivery still reaches the White Noise audit receiver. - Open a busy group during catch-up and confirm member, roster and MLS-state reads return at once.
- Confirm no "history may be incomplete" notice appears without a gap, and
that notices shown under 0.16.0 for
UnprovenHistoryare gone. - With free space for at least four transfers at the largest account limit,
scroll a screen of images and confirm they download in parallel and on-screen
first; fill the disk and confirm downloads show
storageBlockedand resume when space frees. - If adopted: discard a failed send (including one with media) and a still sending one; send a tagged poll and sticker as replies; share a sticker pack link and open it on another device.
- Report evidence by stage: source, host smoke, packaged artifact, consuming app, real device.
What was validated: every change in this comparison landed through the merge queue's CI matrix, and the binding-docs gate passes for the MarmotKit method and C symbol inventories at this source. Not validated here: upgrade of a real 0.16.0 installation, large commits against production relays of unknown limit, and app-level adoption on iOS or Android.
Known limitations:
- A photo in a NIP-22 thread reply stops decrypting once retention prunes the chat messages from its epoch (#3410).
- Startup hydration re-drives every outstanding fanout after each batch of four groups, delaying live transport on accounts with many groups (#3367).
- Pending Welcomes and some other reads still go through the worker queue; moving them is the rest of #3273.
- Relay-safety follow-ups remain open in #3305.
- Still open from earlier releases: adding every device of an account is best effort; right after a reconnect a new send can still go out ahead of older unsent ones; the automatic-rejoin handshake's inner event kind is under discussion (marmot#451); #2237, #2277, #2283, #2389, #2286, #2253, #2158 and #1445.