Port Aeron adapter to wingfoil-next

[0-jake-0]

Ports the classic wingfoil::adapters::aeron module onto the Op model — the Aeron IPC/UDP low-latency message transport — behind the aeron (rusteron-client, C++ FFI) or aeron-rs (pure Rust) backend features, with aeron-driver embedding a media driver in-process. Last entry in Phase 4 item 8.

With this, every classic I/O adapter has a wingfoil-next twin. (The other three of this batch: #598 fluvio, #599 iceoryx2, #600 web.)

Surface

Sources (free builder fns on &GraphBuilder, realtime-only):

• aeron_sub_fragment(&g, run_mode, subscriber, parser, opts) — the typed-parser surface with FragmentHeader access (position, session_id, stream_id) and the Ok(Some) / Ok(None) / Err contract (a malformed fragment is logged and skipped, never aborting the cycle).
• aeron_sub_fragment_with_status(...) — the parallel-additive sibling returning (data, status).

Both polling modes are ported:

Mode	Machinery
Spin (primary)	a busy-spin custom_node polling Aeron inside the cycle on the graph thread
Threaded (secondary)	source_at_start → a background poll thread over the channel layer, with classic's exponential idle back-off

Sink: AeronSinkOps::{aeron_pub, aeron_pub_with_status} on Stream<Burst<T>>, over register_op1, with classic's exact status ordering (Closed terminal and checked first; BackPressure records BackPressured and drops the rest of the burst; a successful offer records Connected; an empty burst falls back to is_connected).

Also carried over: the fragment_limit per-poll cap, the Spin→Threaded downgrade for backends that lock on poll, the ChannelUri builders, ClaimBuffer's zero-copy commit/abort contract, and the TransportError / AeronStatus types. Like classic, the feature uses no async/tokio.

Deviations from classic

Canonical list is in the module's # Deviations from classic block; summarised:

1. The sources take a &GraphBuilder + RunMode, return Result, and reject RunMode::HistoricalFrom at wiring — a live Aeron subscription has no historical timeline, and the threaded mode's channel receiver would block-collect the never-closing poll thread and deadlock at start (register B2, ratified). Classic's spin subscriber silently ran against the fast-forwarded historical clock. The publisher keeps classic's behaviour exactly: its real-time check fires at graph start().
2. The status side-channel is a plain stream, not a node type. Classic's AeronStatusStream (a MutableNode the producer drove via clear()/record() and wired as an active downstream) has no next twin — next multiplexes status with data over one internal envelope and splits it with map_filter, the zmq_sub shape. Observable behaviour (transition-only emission, derivation order, in-band ordering in threaded mode) is identical; notably the spin mode now carries status in-band too.
3. The sink is an extension trait returning Stream<()>, not classic's AeronPub returning Rc<dyn Node>.
4. The mock backends are public test support — next's adapter tests live in tests/ and compile against the public library, so MockSubscriber / MockPublisher can't stay #[cfg(test)]-gated inside the crate.
5. The plain aeron_sub_fragment never derives status — classic's Option<Rc<RefCell<AeronStatusStream>>> becomes a track_status flag. Same behaviour, no allocation.

Tests

• tests/aeron_adapter.rs (aeron) — parity port of the classic node-level unit tests, 20 mock-backed cases needing no media driver: burst shaping (one poll ⇒ one atomic burst), the parser None/Err paths, the synthesised default header, all four status-derivation cases for the subscriber (connected / disconnected / terminal close / steady-state no-re-emission) in both modes, the wiring guards, and the four publisher status cases plus the empty-burst fallback. All green.
• tests/aeron_integration.rs (aeron-integration-test) — parity port of the classic media-driver suite: no-driver connect failure, the three try_claim cases (zero-copy round trip, typed back-pressure, drop-aborts), the fragment_limit cap, spin/threaded/collapse round trips, real fragment positions, both status side-channels over a live driver, the no-dedup publisher, both ChannelUri shapes, and the aeron-rs backend round trip (which is what exercises the Spin→Threaded downgrade end to end).

Docker isn't available in the dev sandbox, so the driver-backed suite was not executed locally; it runs in CI.

Other changes

• examples/aeron/{main.rs,status_circuit_breaker.rs,README.md} — both classic examples ported. The circuit breaker is notable: where classic needed a hand-written MutableNode reading both streams, next expresses it with the ordinary fluent vocabulary (fold latches the transition; a two-input custom_node gates data on it as a passive upstream).
• .github/workflows/aeron-next-integration.yml + registration in integration-tests.yml. The workflow installs the toolchain rusteron's build script needs — cmake ≥3.30 (Ubuntu 24.04 ships 3.28), clang, uuid-dev, libbsd-dev.
• next/docs/port-plan.md Phase 4 item 8 and next/docs/deviation-register.md (B2 scope) updated.

The classic Criterion benches (aeron_publication_latency, aeron_subscription_throughput, aeron_transceiver, aeron_allocation_tracking) are not ported — next's bench suite is a separate work item, as for every adapter so far.

Checks

cargo fmt --all -- --check, cargo lint, cargo lint-all (the full workspace all-features gate — it builds here because the Aeron native toolchain was installed for this port, unlike the earlier adapters in this batch), cargo clippy -p wingfoil-next --all-features --all-targets -- -D warnings, and cargo test -p wingfoil-next --features aeron all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FKhf2tiM8nwtSBzC1St3ga

---

Generated by Claude Code