bytes & OrphanedEnvelope extractor, add delegate_visitor macro

[insipx]

Add BytesExtractor, OrphanExtractor, and delegate_envelope_visitor! to enable Envelope::bytes() and Envelope::orphan() across protocol and collection types

Introduce new extractors and a delegating macro, extend the Envelope and EnvelopeCollection traits with bytes() and orphans(), and wire orphans() through subscribe types; update DB icebox queries to handle multiple cursors with idempotent inserts.

📍Where to Start

Start with the new trait methods in Envelope and EnvelopeCollection in xmtp_api_d14n/src/protocol/traits/envelopes.rs and xmtp_api_d14n/src/protocol/traits/envelope_collection.rs, then review the extractors in xmtp_api_d14n/src/protocol/extractors/bytes.rs and xmtp_api_d14n/src/protocol/extractors/orphaned_envelope.rs, and finally the delegating macro in xmtp_api_d14n/src/protocol/macros.rs.

---

Macroscope summarized e05e925.

[insipx]

This PR is part of a stack of 12 bookmarks:

1. trunk()
2. insipx/causal-fix
3. insipx/icebox-global-cursor
4. insipx/batch-queries
5. insipx/extractors ← this PR
6. insipx/cursor-store-icebox
7. insipx/icebox-in-ordering
8. insipx/test-ordering
9. insipx/paged-stream
10. insipx/ordered-stream
11. insipx/ordered-stream-test
12. push-pnvnmqsyqqqy
13. push-syomxrnuqsnk

---

Created with jj-stack

[claude]

Claude finished @insipx's task —— View job

---

Code Review

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

Key Findings

1. Missing group_id in OrphanExtractor (xmtp_api_d14n/src/protocol/extractors/orphaned_envelope.rs:30)

The OrphanExtractor::get() doesn't set group_id on the OrphanedEnvelope builder. The extractor's inner tuple has a GroupMessageExtractor at position 3, but group_id is never extracted from it:

let mut envelope = OrphanedEnvelope::builder();
envelope.cursor(extracted.0.get()?);
envelope.depends_on(extracted.1.get().unwrap_or_default());
envelope.payload(extracted.2.get());
// Missing: envelope.group_id(extracted.3.get()?.group_id);
Ok(envelope.build()?)

This was already noted by macroscopeapp but remains unaddressed.

2. Test implementation incompleteness (xmtp_api_d14n/src/protocol/utils/test/test_envelope.rs:94-96)

The TestEnvelope::orphan() method uses todo!() rather than unreachable!() like other unimplemented methods. This inconsistency suggests incomplete test infrastructure:

fn orphan(&self) -> Result<xmtp_proto::types::OrphanedEnvelope, EnvelopeError> {
    todo!()  // Should be unreachable!() or implemented
}

3. Potential double-encoding in BytesExtractor (xmtp_api_d14n/src/protocol/extractors/bytes.rs:35-38)

The visit_originator method encodes the OriginatorEnvelope, then the visitor pattern calls accept which will encode the nested envelope. This may produce concatenated bytes rather than just the protobuf body. See macroscopeapp's comment - this needs clarification on intended behavior.

4. Coverage concerns

The codecov report shows 45.40% patch coverage with 208 missing lines. Critical paths include:

• The entire delegate_envelope_visitor! macro (144 lines, 0% coverage)
• BytesExtractor implementation (18 lines, 0% coverage)
• OrphanExtractor implementation (8 lines, 0% coverage)

While macro-generated code is hard to test directly, the extractors should have unit tests demonstrating they work correctly across envelope types.

Positive aspects

• Clean macro design for reducing boilerplate in delegate_envelope_visitor!
• Consistent trait extension pattern for bytes() and orphans() methods
• Good use of idempotent inserts (on_conflict_do_nothing) in database layer
• Well-structured visitor pattern implementation

---

[codecov]

Codecov Report

❌ Patch coverage is 45.40682% with 208 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.80%. Comparing base (d704e2f) to head (e05e925).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
xmtp_api_d14n/src/protocol/macros.rs	0.00%	144 Missing ⚠️
xmtp_api_d14n/src/protocol/extractors/bytes.rs	0.00%	18 Missing ⚠️
xmtp_api_d14n/src/protocol/traits/envelopes.rs	0.00%	10 Missing ⚠️
..._api_d14n/src/protocol/impls/protocol_envelopes.rs	0.00%	9 Missing ⚠️
..._d14n/src/protocol/extractors/orphaned_envelope.rs	0.00%	8 Missing ⚠️
xmtp_db/src/encrypted_store/icebox.rs	95.45%	8 Missing ⚠️
xmtp_api_d14n/src/protocol/sort/timestamp.rs	0.00%	4 Missing ⚠️
..._api_d14n/src/protocol/utils/test/test_envelope.rs	0.00%	4 Missing ⚠️
...pi_d14n/src/protocol/traits/envelope_collection.rs	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2868      +/-   ##
==========================================
- Coverage   73.98%   73.80%   -0.19%     
==========================================
  Files         398      401       +3     
  Lines       50905    51274     +369     
==========================================
+ Hits        37661    37841     +180     
- Misses      13244    13433     +189     

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