docs: reflect group distribution lane serialization (whatsapp-rust#1043)

[jlucaso1]

Summary

Documents oxidezap/whatsapp-rust#1043 ("fix(signal): serialize sender-key mutations"):

• advanced/signal-protocol.mdx — three new notes under the sender-keys section:
  • the per-group distribution lane now guards the full audit → reset → redistribute sequence (SKDM fan-out, participant-removal rotation, forced own-key rotation, status sends, phash-mismatch recovery, periodic rotation) instead of just the cold SKDM send, closing a race where a concurrent encrypt could restore a retired key after deletion
  • reset_sender_key_device_tracking is DB-first: it clears tracking durably before invalidating the in-memory cache, with a cold-mark fallback if the clear fails, and the unknown-participant retry-rotation path now flushes before any later throttle in the same call can return early
  • the new memory_report() counters for distribution-lane pressure
• api/client.mdx — three new MemoryReport fields: group_distribution_locks, group_distribution_lock_evictions, group_distribution_lock_eviction_blocks
• api/bot.mdx — updated the group_distribution_locks_capacity cache-config description to match the new soft-cap semantics (a live lane is never evicted) and cross-referenced the new memory_report() counters

Per project convention (see CLAUDE.md), the changelog/ directory is left untouched — that's maintained by a human.

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Summary by cubic

Update docs: the per-group sender-key distribution lane covers the full audit → reset → redistribute sequence to prevent races in SKDM fan-out, rotations, status sends, and recovery.
Also document DB-first tracker resets with a cold-mark fallback, add memory_report() counters (group_distribution_locks, group_distribution_lock_evictions, group_distribution_lock_eviction_blocks), clarify the group_distribution_locks_capacity soft-cap semantics, and fix a stale clear_sender_key_devices reference to reset_sender_key_device_tracking.

^{Written for commit 5a5a85f. Summary will update on new commits.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
whatsapp-rust	🟢 Ready	View Preview	Jul 15, 2026, 11:33 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This documentation-only PR reflects the changes landed in whatsapp-rust#1043, which expanded the per-group sender-key distribution lane to guard the entire audit → reset → redistribute sequence and switched tracker resets to a DB-first strategy with a cold-mark fallback.

• advanced/signal-protocol.mdx — stale clear_sender_key_devices reference on the rotation bullet corrected to reset_sender_key_device_tracking; three new Notes covering lane-scope expansion (race closure), DB-first reset semantics (fail-closed ordering), and the new memory_report() observability counters. All internal anchors (#parallelized-group-encrypt-fan-out, /api/bot#cache-configuration-reference, /api/client#memory_report, /advanced/retry-admission) verified present.
• api/bot.mdx — group_distribution_locks_capacity description updated from "single-flights cold SKDM" to the new soft-cap semantics; Note added cross-referencing the three new counters in memory_report().
• api/client.mdx — three new rows (group_distribution_locks, group_distribution_lock_evictions, group_distribution_lock_eviction_blocks) added to the MemoryReport table, consistent with the descriptions in both other files.

Confidence Score: 5/5

Documentation-only change; all internal links resolve and descriptions are mutually consistent across the three files.

Every cross-file link was verified (anchors exist in the target files), the stale clear_sender_key_devices reference flagged in a prior review is correctly updated, and the three new MemoryReport field descriptions match their counterparts in both api/bot.mdx and advanced/signal-protocol.mdx. No executable code is touched.

No files require special attention.

Important Files Changed

Filename	Overview
advanced/signal-protocol.mdx	Three new Notes added under the sender-keys section covering lane-scope expansion, DB-first tracker resets, and observability counters; the clear_sender_key_devices reference on line 645 correctly updated to reset_sender_key_device_tracking, addressing the stale-reference concern from a prior review. All internal anchors verified correct.
api/bot.mdx	Updated group_distribution_locks_capacity description from single-flight cold SKDM to soft-cap semantics; added a Note cross-referencing the three new memory_report() counters. Note is correctly placed after the last row of the coordination-caches table and before #### Sent message DB cleanup.
api/client.mdx	Three new MemoryReport fields inserted after chat_lanes: group_distribution_locks, group_distribution_lock_evictions, group_distribution_lock_eviction_blocks. Descriptions are consistent with the counterpart Note in api/bot.mdx and the Observability Note in advanced/signal-protocol.mdx.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Group send / rotate / status / recovery] --> B[Acquire per-group distribution lane]
    B --> C{Lane live?}
    C -- Yes --> D[Temporarily exceed capacity soft cap\nincrement eviction_blocks counter]
    C -- No / new --> E[Take lane]
    D --> E
    E --> F[Delete own sender key if rotating]
    F --> G[reset_sender_key_device_tracking]
    G --> H{DB clear success?}
    H -- Yes --> I[Invalidate in-memory SenderKeyDeviceCache]
    H -- No --> J[Mark all tracked rows cold\nhas_key=false]
    J --> K{Cold-mark success?}
    K -- No --> L[Return error — fail-closed]
    K -- Yes --> I
    I --> M[SKDM fan-out / redistribution]
    M --> N[Release distribution lane]
    N --> O[Increment evictions counter if cold lane evicted]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Group send / rotate / status / recovery] --> B[Acquire per-group distribution lane]
    B --> C{Lane live?}
    C -- Yes --> D[Temporarily exceed capacity soft cap\nincrement eviction_blocks counter]
    C -- No / new --> E[Take lane]
    D --> E
    E --> F[Delete own sender key if rotating]
    F --> G[reset_sender_key_device_tracking]
    G --> H{DB clear success?}
    H -- Yes --> I[Invalidate in-memory SenderKeyDeviceCache]
    H -- No --> J[Mark all tracked rows cold\nhas_key=false]
    J --> K{Cold-mark success?}
    K -- No --> L[Return error — fail-closed]
    K -- Yes --> I
    I --> M[SKDM fan-out / redistribution]
    M --> N[Release distribution lane]
    N --> O[Increment evictions counter if cold lane evicted]

Loading

_{Reviews (2): Last reviewed commit: "docs: fix stale clear_sender_key_devices..." | Re-trigger Greptile}