Marmot
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
  • Start here

    • Documentation
  • Integration guides

    • Native apps · MarmotKit
    • Rust application runtime
    • C and native hosts
    • Bots and agents
    • Terminal and scripts
    • TypeScript quickstart
    • TypeScript storage
    • TypeScript networking
  • Reference

    • MarmotKit distribution
    • MarmotKit API
    • C API
    • Architecture
    • Upgrade guide

Upgrade guide

MDK 0.17.0View source on GitHub

This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.

Upgrading MDK 0.16.0 → 0.17.0

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

  1. 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.

  2. 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 creates String (group id) GroupCreationResultFfi
    createGroupDetailed, createGroupWithOptionsDetailed, createGroupWithInitialImageDetailed CreatedGroupFfi DetailedGroupCreationResultFfi
    inviteMembers, inviteMembersWithInitialAdmins SendSummaryFfi InviteMembersResultFfi
    inviteMembersDetailed, inviteMembersDetailedWithInitialAdmins GroupMutationResultFfi GroupInviteResultFfi

    Other detailed group mutations keep GroupMutationResultFfi, and startDirectConversation keeps its signature: it stays all-or-nothing.

  3. Replace the audit source setter. setAuditLogSource(AuditLogSourceFfi) takes the same hardwareModel, platform and appVersion as the removed AuditLogTrackerConfigV4Ffi minus 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. Remove postAuditLogFile and postAuditLogTrackerUpdate; keep calling postAuditLogTrackerUpdateV5, whose AuditLogTrackerUpdateResultV5Ffi now holds only enabled and v5. Builds no longer embed MARMOT_AUDIT_LOG_TRACKER_ENDPOINT. MarmotServiceEndpoints no longer carries a tracker endpoint. Local v4 files stay listable and deletable until retention expires them, and startup deletes the orphaned audit-upload-checkpoint.json.

    _ = try kit.setAuditLogSource(source: AuditLogSourceFfi(
        hardwareModel: systemModelIdentifier(), platform: "ios", appVersion: appVersion))
    
    marmot.setAuditLogSource(AuditLogSourceFfi(Build.MODEL, "android", appVersion))
    
  4. Handle MarmotKitError.CreatedGroupMemberReportUnavailable(groupIdHex:) (Kotlin MarmotKitException.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.

  5. Remove reads of AppPerformanceSnapshotFfi.accountGroupReadSnapshot. The startup group-read snapshot it timed no longer exists, because group reads answer from the published read state. accountProfileLoad stays and now times the profile load each member read takes.

  6. Keep HistoryNoticeCauseFfi.UnprovenHistory in 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 }. status is selected, missingKeyPackage, obsoleteKeyPackage, invalidKeyPackage, incompatibleKeyPackage, missingInboxRoute or incomplete; selectedDeviceCount is zero for every status but selected.

Read the result in this order:

  1. If the operation (groupIdHex, created or summary) 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.
  2. If it is present, a create's group is canonical locally. An invite's summary keeps its 0.16.0 meaning: read summary.acceptDisposition as before. published means the commit went out; acceptedPending means the invite is queued while the group settles and can still be refused (QueuedIntentRefused); completionUnknown means the commit is unresolved. Keep showing those members as pending until the change settles. In every case, show the accounts that were not selected, for example as "could not be added".
  3. selected means MDK found fresh, compatible devices and a safe inbox route. It is not a join or a Welcome delivery: keep using pendingWelcomeDeliveries and WelcomeDeliveryPending for 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, groupMlsState and its diagnostic form, groupRoster / groupConversationSnapshot, and groupAppComponent.

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, nevent1 or naddr1 reference with a valid bech32 checksum is now a MarkdownInlineFfi NostrUri instead of text, so copied note ids can render as event cards. An invalid checksum stays text; bare npub mentions and explicit nostr: 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; stillSending when the group has a send the engine may still publish, which could be this one (nothing changed; try again later); or notFailedSend for 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_hex NULL when no group was created) or MarmotDetailedGroupCreationResult (created NULL likewise); invite outputs are MarmotInviteMembersResult (summary NULL when nothing changed) or MarmotGroupInviteResult. Each carries member_outcomes / member_outcomes_len of MarmotMemberResolutionOutcome. Free each root with marmot_group_creation_free, marmot_detailed_creation_free, marmot_invite_members_free or marmot_group_invite_free, never marmot_string_free or marmot_send_summary_free. marmot_created_group_free is removed; the created group is embedded in the detailed result.
  • MARMOT_STATUS_CREATED_GROUP_MEMBER_REPORT_UNAVAILABLE (130) is the C form of CreatedGroupMemberReportUnavailable; open the group the error detail names.
  • marmot_set_audit_log_source replaces marmot_set_audit_log_tracker_config and marmot_set_audit_log_tracker_config_v4. It borrows a MarmotAuditLogSource (hardware_model, platform, app_version) and returns a copy freed with marmot_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. MarmotAuditLogTrackerUpdateResultV5 drops v4_uploaded, v4_uploaded_len and v4_skipped_reason.
  • MarmotAppPerformanceSnapshot drops account_group_read_snapshot.
  • MarmotGroupCommitDelivery appends refused_relays / refused_relays_len after since, each a MarmotGroupCommitRefusedRelay (relay_url, a MarmotGroupCommitRefusalCause, has_size_class / size_class), freed by marmot_group_commit_delivery_free.
  • New: marmot_discard_failed_send (free with marmot_discard_failed_send_result_free); marmot_create_tagged_poll and marmot_send_tagged_sticker, which borrow MarmotStringArray tag rows; marmot_sticker_pack_share_link, whose string you free with marmot_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 and invite_members* return GroupMemberResult<T> (operation: Option<T>, member_outcomes). invite_members_with_initial_admins takes a MemberResolutionPolicy, and AppCreateGroupOptions gains member_resolution; Partial, the default, proceeds with available members and Atomic keeps the all-or-nothing behavior, failing with the directory error when any member is unavailable. AppError gains CreatedGroupMemberReportUnavailable.
  • marmot-app audit: post_audit_log_file, AuditLogUploadResult, AuditLogTrackerConfig, set_audit_log_tracker_config and MarmotServiceEndpoints::audit_log_tracker_endpoint are removed. Use MarmotAppRuntime::set_audit_log_source(AuditLogSource). AuditLogTrackerUpdateResult keeps only enabled and v5.
  • marmot-app commit delivery: GroupCommitDelivery gains refused_relays: Vec<GroupCommitRefusedRelay>; struct literals add it.
  • storage-sqlite: list_prepared_group_image_uploads is replaced by list_prepared_group_image_upload_statuses (statuses without image data or secrets; use prepared_group_image_upload(upload_id) for one full record), and account_group_self_memberships by the per-group group_standing.
  • marmot-app reads: AppPerformanceSnapshot drops account_group_read_snapshot; MarmotAppConfig drops dev_force_group_read_snapshot_failure and its builder.
  • marmot-app downloads: storage-blocked downloads park as described in Attachment downloads. SqliteAppStorage::readmit_storage_blocked_attachments takes a need function, and request_automatic_attachment returns whether the order changed.
  • cgka_traits: TransportPeeler::peel_group_message takes &PreparedGroupMessage<'_>. Move context-independent validation and decoding into prepare_group_message (the default borrows the raw payload); a wrapping peeler delegates preparation to the peeler that decrypts. GroupStorage::put_group is replaced by put_group_with_roster(group, committed) for writes that merge, clear or re-derive membership and put_group_keeping_roster(group) for every other write. StorageProvider requires CommittedRosterStorage and adds has_atomic_group_savepoints, past_peel_context_generation and mls_storage_failure, each with a safe default.
  • cgka_traits transport: TransportEndpointFailure gains pre_send: bool; struct literals must set it. Set it true only 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's rate-limited: or auth-required: answer is never pre-send. false counts the target as possibly exposed, so a later refusal there no longer rolls back the commit. TransportAdapter adds commit_size_refusals (default refuses nothing) and publish_commit (default publish); an adapter that applies the 64 KiB commit floor at relays of unknown limit overrides both.
  • nostr-directory: Directory::resolve_compatible_member_key_packages takes a MemberResolutionPolicy, and ResolvedMemberKeyPackages gains member_outcomes. Pass Atomic for the previous behavior, which fails on the first unavailable member; Partial returns per-account outcomes.
  • storage-sqlite: RecoveryUnitPolicy gains probe_base_seconds and probe_cap_seconds; dismiss_recovery_route_park and dismiss_recovery_route_park_on are removed. put_group stays only under test-support.
  • Engine, session and runtime add durably_owned_key_packages_with_validity, and durably_owned_key_packages now fails with the storage error when a stored bundle cannot be read.
  • marmot-forensics adds three v5 audit kinds (recovery_runner_fetched, recovery_runner_raced, recovery_runner_changed) and their vocabularies.
  • The incident-replay crate 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-proto 0.11.19 and quinn-udp 0.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_generation of None stays 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.isDm follows 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 incomplete in 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 MessageEditedOrReprojected and ReplyPreviewChanged instead of ReactionAdded, 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/when updated; 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 setAuditLogSource runs 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 UnprovenHistory are 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 storageBlocked and 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.
Prev
Architecture
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
©2025–2026 Internet Privacy Foundation. All rights reserved.
Marmot