docs: reflect tombstone durability-gate retention (whatsapp-rust#1042)

[jlucaso1]

Summary

Reflects whatsapp-rust#1042 ("fix(signal): retain durability gates through deletes"), which:

• Kept a pending session-reservation gate attached when an entry becomes a tombstone (session delete), instead of clearing it as soon as the delete was applied to the in-memory cache.
• Did the same for sender-key wire gates.
• Released each gate only after its matching backend delete actually succeeds — a failed delete keeps needs_pre_wire_flush() returning true and is retried on the next flush.

Previously, a concurrent delete could release a durability gate before the backend delete was actually persisted, letting ciphertext reach the wire while the pre-delete chain state was still recoverable — a crash or failed delete in that window could reload the old state and re-derive already-used key material.

Changes

• advanced/signal-protocol.mdx — added a paragraph after the existing "pre-wire gate" warning in "Flush scheduling: send vs. receive," describing the new tombstone gate-retention behavior for both session and sender-key deletes, and noting that a lossy clear() still drops a pending tombstone gate (no backend delete left to wait for).

Not touched: changelog/ (per project convention, that's maintained by a human).

Test plan

• Read the wacore/src/store/signal_cache.rs diff for whatsapp-rust#1042 (including the new pre_wire_gate_tests barrier-backend tests) to verify the doc wording against the actual gate-release ordering.
• mint broken-links (not run locally in this environment).

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Summary by cubic

Update advanced/signal-protocol.mdx to document that session and sender-key deletes keep a pending pre-wire durability gate on the tombstone until the backend delete succeeds, preventing sends while pre-delete state is still recoverable. Also clarifies that failed deletes keep needs_pre_wire_flush() true for retry, and that a lossy clear() drops the pending delete (it discards the tombstone without calling delete_session/delete_sender_key), so stale chain state may remain in the backend.

^{Written for commit 7a296ca. Summary will update on new commits.}

[coderabbitai]

Warning

Review limit reached

@jlucaso1, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 27 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d705b014-5105-4503-8765-2b9652657edf

📥 Commits

Reviewing files that changed from the base of the PR and between c177e1a and 7a296ca.

📒 Files selected for processing (1)

• advanced/signal-protocol.mdx

---

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

[mintlify]

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

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

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

[greptile-apps]

Greptile Summary

This is a documentation-only update to advanced/signal-protocol.mdx that reflects the gate-retention fix from whatsapp-rust#1042. The added paragraph explains that deleting a session or sender-key record now keeps any open durability gate alive on the resulting tombstone until the backend delete succeeds, preventing ciphertext from reaching the wire while recoverable pre-delete chain state exists.

• A new paragraph inserted after the existing pre-wire-gate warning describes the tombstone gate-retention behavior for both session and sender-key deletes, the retry-on-failure property, and the security regression it closes.
• The clear() edge case is correctly noted: the in-memory tombstone is discarded without ever issuing the backend delete, so the old chain state may remain in the backend — this is an acknowledged limitation, not a regression.

Confidence Score: 5/5

Documentation-only change with no runtime code modifications; safe to merge.

The change is a single paragraph addition to a documentation file. The wording accurately describes the tombstone gate-retention behavior, the retry-on-failed-delete property, and the clear() edge case (discards the tombstone without issuing the backend delete). The previous reviewer concern about the clear() clause has been addressed in the current wording. No code paths are touched.

No files require special attention.

Important Files Changed

Filename	Overview
advanced/signal-protocol.mdx	Added one paragraph documenting tombstone durability-gate retention for session/sender-key deletes; wording is technically accurate and the clear() caveat correctly describes the in-memory-only discard without a backend delete.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Task
    participant SignalStoreCache
    participant Backend

    Note over Task,Backend: New behavior (whatsapp-rust#1042)
    Task->>SignalStoreCache: delete_session / delete_sender_key
    SignalStoreCache->>SignalStoreCache: mark entry as tombstone (keep durability gate open)
    Task->>SignalStoreCache: needs_pre_wire_flush()?
    SignalStoreCache-->>Task: true (gate still open)
    Task->>SignalStoreCache: flush()
    SignalStoreCache->>Backend: delete_session / delete_sender_key
    alt Backend delete succeeds
        Backend-->>SignalStoreCache: Ok
        SignalStoreCache->>SignalStoreCache: release durability gate
        SignalStoreCache-->>Task: Ok
        Task->>Task: write stanza to wire
    else Backend delete fails
        Backend-->>SignalStoreCache: Err
        SignalStoreCache->>SignalStoreCache: keep gate open (retry on next flush)
        SignalStoreCache-->>Task: Err
        Task->>Task: abort send
    end

    Note over Task,Backend: clear() edge case
    Task->>SignalStoreCache: clear()
    SignalStoreCache->>SignalStoreCache: discard tombstone (no backend delete issued)
    Note over Backend: old chain state may remain in backend

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"}}}%%
sequenceDiagram
    participant Task
    participant SignalStoreCache
    participant Backend

    Note over Task,Backend: New behavior (whatsapp-rust#1042)
    Task->>SignalStoreCache: delete_session / delete_sender_key
    SignalStoreCache->>SignalStoreCache: mark entry as tombstone (keep durability gate open)
    Task->>SignalStoreCache: needs_pre_wire_flush()?
    SignalStoreCache-->>Task: true (gate still open)
    Task->>SignalStoreCache: flush()
    SignalStoreCache->>Backend: delete_session / delete_sender_key
    alt Backend delete succeeds
        Backend-->>SignalStoreCache: Ok
        SignalStoreCache->>SignalStoreCache: release durability gate
        SignalStoreCache-->>Task: Ok
        Task->>Task: write stanza to wire
    else Backend delete fails
        Backend-->>SignalStoreCache: Err
        SignalStoreCache->>SignalStoreCache: keep gate open (retry on next flush)
        SignalStoreCache-->>Task: Err
        Task->>Task: abort send
    end

    Note over Task,Backend: clear() edge case
    Task->>SignalStoreCache: clear()
    SignalStoreCache->>SignalStoreCache: discard tombstone (no backend delete issued)
    Note over Backend: old chain state may remain in backend

Loading

_{Reviews (2): Last reviewed commit: "docs: clarify clear() drops the pending ..." | Re-trigger Greptile}