make Cursor non-exhaustive

[insipx]

just a QoL change that removes some lines and allows more assumptions to be made in Cursor type implementation

[insipx]

This PR is part of a stack of 1 bookmark:

1. trunk()
2. insipx/seal-cursor ← this PR

---

Created with jj-stack

[claude]

Claude finished @insipx's task —— View job

---

Code Review Complete ✅

Review Date: December 11, 2025, 16:30 UTC

Tasks

• Read core cursor type changes
• Review constructor patterns and API design
• Check for unreported bugs or issues
• Assess test coverage gaps
• Provide final review feedback

---

Summary

This PR successfully refactors Cursor to be non-exhaustive, forcing constructor usage instead of struct literals. The change is well-executed with excellent test coverage. I found one additional issue beyond what's already been commented on.

Issues Found

1. Missing Test Coverage for #[cfg(test)] Generate Implementation

Location: xmtp_proto/src/types/cursor.rs:86-94

The Generate trait implementation for Cursor still uses direct struct construction in test code:

#[cfg(any(test, feature = "test-utils"))]
impl xmtp_common::Generate for Cursor {
    fn generate() -> Self {
        Cursor {                           // Direct construction
            sequence_id: xmtp_common::rand_u64(),
            originator_id: openmls::test_utils::random_u32(),
        }
    }
}

Issue: While this is allowed within the same crate due to the #[cfg(test)] gate, it bypasses the constructor pattern. If Cursor gains new fields in the future, this test utility won't enforce proper initialization.

Recommendation: Update to use Cursor::new() for consistency:

fn generate() -> Self {
    Cursor::new(xmtp_common::rand_u64(), openmls::test_utils::random_u32())
}

2. Hardcoded Cursor in stream_messages.rs (Already Noted)

Location: xmtp_mls/src/subscriptions/stream_messages.rs:262

Macroscope already identified this issue - the hardcoded cursor ignores the topic_cursor parameter and contradicts the function documentation.

Positive Observations

1. Excellent API Design: The typed constructors (v3_welcomes(), mls_commits(), etc.) provide a type-safe, self-documenting API that's superior to raw struct construction.

2. Comprehensive Refactoring: The PR touches 23 files and successfully eliminates 390 lines of boilerplate while improving API safety.

3. Strong Test Coverage: 89.69% patch coverage with thorough tests for the constructor methods (xmtp_proto/src/types/cursor.rs:140-164).

4. Good Use of const fn: All typed constructors are const, allowing compile-time evaluation when possible.

5. Proper IntoIterator Implementation: The PR maintains the existing iterator implementations, ensuring no breaking changes to iteration patterns.

Minor Notes

• The new() constructor uses a generic Into<u32> for originator_id, which provides nice ergonomics for passing both u32 and the Originators constants.
• The code quality is high with appropriate use of #[non_exhaustive] to prevent ad-hoc construction while maintaining field access.

---

[macroscopeapp]

Make xmtp_proto::types::Cursor non-exhaustive and replace all struct literals with Cursor::new(...) across protocol, DB, MLS, and tests

Annotates xmtp_proto::types::Cursor with #[non_exhaustive] and refactors all call sites to construct cursors via Cursor::new(...) (and helpers like Cursor::mls_commits(...) and Cursor::v3_welcomes(...)), replacing direct struct literals in protocol extractors, DB stores/queries, MLS subscriptions/streams, and tests. Key definition change is in cursor.rs.

📍Where to Start

Start with the Cursor definition and constructors in cursor.rs, then review call-site refactors such as GlobalCursor usage in global_cursor.rs.

---

Macroscope summarized 5f7751f.

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.69%. Comparing base (418c978) to head (5f7751f).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
xmtp_proto/src/types/global_cursor.rs	66.66%	2 Missing ⚠️
xmtp_mls/src/subscriptions/process_welcome.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2917      +/-   ##
==========================================
- Coverage   73.78%   73.69%   -0.10%     
==========================================
  Files         401      401              
  Lines       51265    51031     -234     
==========================================
- Hits        37828    37609     -219     
+ Misses      13437    13422      -15     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.