# Upgrade guide

> MDK 0.17.0 · [Read on Marmot](https://marmot.build/docs/upgrading.html) · [Version-pinned source](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/integration/0.17.0.md)

## 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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/release/0.17.0.md), [previous upgrade guide](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/integration/0.16.0.md), and [current binding reference](https://marmot.build/docs/native-apps.html).

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](https://marmot.build/docs/upgrading.html#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](https://marmot.build/docs/upgrading.html#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](https://marmot.build/docs/distribution.html).
    
2.  Adopt the create and invite results. See [Partial group creates and invites](https://marmot.build/docs/upgrading.html#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`.
    
    ```swift
    _ = try kit.setAuditLogSource(source: AuditLogSourceFfi(
        hardwareModel: systemModelIdentifier(), platform: "ios", appVersion: appVersion))
    ```
    
    ```kotlin
    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](https://marmot.build/docs/upgrading.html#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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/storage-format-v2.md).

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

```swift
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) }
```

```kotlin
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](https://marmot.build/docs/upgrading.html#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`.

```swift
let result = try await kit.discardFailedSend(
    accountRef: account, groupIdHex: group, messageIdHex: message)
if result.outcome == .discarded { purgeMediaCache(result.mediaCiphertextSha256) }
```

```kotlin
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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/marmot-uniffi/POLLS.md) and [stickers](https://marmot.build/docs/native-apps.html#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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/marmot-uniffi/NATIVE-HOST-TESTS.md) 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.

```c
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](https://marmot.build/docs/c-interface.html) and [symbol inventory](https://marmot.build/docs/c-api.html).

## 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](https://marmot.build/docs/upgrading.html#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](https://github.com/marmot-protocol/mdk/issues/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](https://github.com/marmot-protocol/mdk/issues/3410)).
*   Startup hydration re-drives every outstanding fanout after each batch of four groups, delaying live transport on accounts with many groups ([#3367](https://github.com/marmot-protocol/mdk/issues/3367)).
*   Pending Welcomes and some other reads still go through the worker queue; moving them is the rest of [#3273](https://github.com/marmot-protocol/mdk/issues/3273).
*   Relay-safety follow-ups remain open in [#3305](https://github.com/marmot-protocol/mdk/issues/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](https://github.com/marmot-protocol/marmot/issues/451)); [#2237](https://github.com/marmot-protocol/mdk/issues/2237), [#2277](https://github.com/marmot-protocol/mdk/issues/2277), [#2283](https://github.com/marmot-protocol/mdk/issues/2283), [#2389](https://github.com/marmot-protocol/mdk/issues/2389), [#2286](https://github.com/marmot-protocol/mdk/issues/2286), [#2253](https://github.com/marmot-protocol/mdk/issues/2253), [#2158](https://github.com/marmot-protocol/mdk/issues/2158) and [#1445](https://github.com/marmot-protocol/mdk/issues/1445).
