docs(signal-protocol): retry-not-nack for aged-out InvalidSignedPreKeyId

[jlucaso1]

Summary

Documents the fix from oxidezap/whatsapp-rust#987.

• advanced/signal-protocol.mdx — in the "Signed pre-key rotation (RotateKeyJob)" section, adds a paragraph explaining that when a peer's PreKeySignalMessage names a signed prekey that has aged past SIGNED_PRE_KEY_RETENTION (genuinely gone, not just a backend-table miss), the 1:1 decrypt path now sends a retry receipt (RetryReason::InvalidKeyId) instead of falling through to the catch-all NACK — mirroring the existing InvalidPreKeyId arm. Previously this case fell through to a terminal NACK, silently and permanently dropping the 1:1 message from the offline queue.
• Updates the Location line for that subsection to include src/message/receive.rs.

Why

The upstream PR changes the receive-path error classification for SignalProtocolError::InvalidSignedPreKeyId. This doc's "Signed pre-key rotation" section already explained the pre-fix backend-fallback bug for this same error variant, so it's the natural place to record the follow-up decrypt-path behavior.

Not included

Per the task instructions, no changelog entries were added — those are human-authored only.

---

Generated by Claude Code

---

Summary by cubic

Document the change to send a retry receipt (RetryReason::InvalidKeyId) instead of a NACK when a PreKeySignalMessage references a signed pre-key id past SIGNED_PRE_KEY_RETENTION on the 1:1 decrypt path. This prevents silent message loss and matches the existing InvalidPreKeyId handling; also updates the Location list to include src/message/receive.rs.

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

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 40 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: 5f6a708c-2bf1-4199-8412-55b044853011

📥 Commits

Reviewing files that changed from the base of the PR and between 93df57d and 5c56940.

📒 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 6, 2026, 10:03 PM

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

[greptile-apps]

Greptile Summary

This is a documentation-only PR that records the behavior change introduced in upstream PR #987: when a PreKeySignalMessage names a signed pre-key that has aged past SIGNED_PRE_KEY_RETENTION, the 1:1 decrypt path now sends a retry receipt instead of a silent terminal NACK.

• Adds a new inline bold paragraph ("Retry, not NACK…") immediately after the existing "Backend fallback for rotated-out ids" paragraph, explaining that InvalidSignedPreKeyId on the receive path now routes to RetryReason::InvalidKeyId rather than UnhandledError nack.
• Updates the Location line for the "Signed pre-key rotation" subsection to include src/message/receive.rs.

Confidence Score: 5/5

Documentation-only change; no executable code is modified.

The single changed file is a .mdx doc page. The new paragraph accurately describes the before/after behavior (UnhandledError nack → RetryReason::InvalidKeyId retry receipt), the SIGNED_PRE_KEY_RETENTION count (3 total) is consistent with the surrounding text, and the added src/message/receive.rs entry in the Location line correctly reflects where the receive-path change lives. Nothing in the diff can regress runtime behavior.

No files require special attention.

Important Files Changed

Filename	Overview
advanced/signal-protocol.mdx	Adds one explanatory paragraph and updates the Location line for the signed pre-key rotation subsection; content is accurate and consistent with surrounding documentation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Incoming PreKeySignalMessage\n(1:1 decrypt path)"] --> B["load_signed_prekey(id)"]
    B --> C{ID matches\ncurrent key?}
    C -- Yes --> D["Decrypt normally"]
    C -- No --> E["Backend table fallback\n(non-current ids)"]
    E --> F{Found in\nbackend table?}
    F -- Yes --> D
    F -- No --> G["InvalidSignedPreKeyId\n(aged past SIGNED_PRE_KEY_RETENTION)"]
    G --> H["BEFORE: UnhandledError NACK\n⚠️ stanza dropped from offline queue\n(message lost permanently)"]
    G --> I["AFTER: RetryReason::InvalidKeyId\nretry receipt + current bundle sent\n(mirrors InvalidPreKeyId arm)"]
    style H fill:#ffcccc,stroke:#cc0000
    style I fill:#ccffcc,stroke:#006600

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["Incoming PreKeySignalMessage\n(1:1 decrypt path)"] --> B["load_signed_prekey(id)"]
    B --> C{ID matches\ncurrent key?}
    C -- Yes --> D["Decrypt normally"]
    C -- No --> E["Backend table fallback\n(non-current ids)"]
    E --> F{Found in\nbackend table?}
    F -- Yes --> D
    F -- No --> G["InvalidSignedPreKeyId\n(aged past SIGNED_PRE_KEY_RETENTION)"]
    G --> H["BEFORE: UnhandledError NACK\n⚠️ stanza dropped from offline queue\n(message lost permanently)"]
    G --> I["AFTER: RetryReason::InvalidKeyId\nretry receipt + current bundle sent\n(mirrors InvalidPreKeyId arm)"]
    style H fill:#ffcccc,stroke:#cc0000
    style I fill:#ccffcc,stroke:#006600

Loading

_{Reviews (1): Last reviewed commit: "docs(signal-protocol): document retry-no..." | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Auto-approved: Documentation-only update adding a paragraph about retry behavior for an edge case. No source code changes, low risk.

Re-trigger cubic</sub>