core(mailbox): principal-grade redesign — evaluate channel primitive + composable API

[joeldsouzax]

Follows #112 (PR #132, not merged — we redesign before it lands). The v1 mailbox shipped missing two things its own rigor contract required, and the API is not principal-grade.

The gaps (why this card exists)

1. No channel-primitive evaluation — the survey core(mailbox): rebuild from kameo reference — queue + Signal + backpressure #112 explicitly required was skipped. core(mailbox): rebuild from kameo reference — queue + Signal + backpressure #112 mandated: "Existing crates: tokio::sync::mpsc, flume, thingbuf, async-channel, crossbeam-channel… Decide the primitive" and "Research — Vyukov intrusive MPSC, LMAX Disruptor, thingbuf design. No commitment before the survey." v1 defaulted to tokio::sync::mpsc with zero measured comparison. That is a skipped part of the contract, not a justified default.
2. The API does not compose. bounded() is a free-floating function; Capacity is a separate value that doesn't flow into construction. The surface is procedural, not composable/functional.
3. Not principal-grade cohesion across the Signal / error / weak-sender / construction surface.

Scope

A. Channel-primitive evaluation (measured, evidence-first)

Criterion benchmarks of the candidates under the mailbox's actual access pattern (bounded MPSC, Signal<A> element by value, 1 consumer + N contended producers), on the axes that matter here:

• enqueue latency (uncontended) + contended throughput (N producers)
• memory / allocations per message + idle per-mailbox footprint
• async-native integration (the run-loop selects over the receiver, core(actor): rebuild from kameo reference — Actor trait, lifecycle hooks, run-loop #116)
• no_std / loom / shuttle story — load-bearing for the core(actor): rebuild from kameo reference — Actor trait, lifecycle hooks, run-loop #116/core(supervision): rebuild from kameo reference — links, death-watch, restart strategies #120 DST that core(mailbox): rebuild from kameo reference — queue + Signal + backpressure #112 deferred, and for M6 lite-bombay (no_std)
• maturity / maintenance

Candidates: tokio::sync::mpsc, flume, thingbuf, async-channel, crossbeam-channel (+ the Vyukov-intrusive / LMAX-disruptor designs as reference). Pick on the numbers; document the decision + the table. If the winner isn't tokio, it lands behind a small channel seam (which also unblocks the deferred loom/shuttle DST).

B. Composable / functional API

Rework construction so capacity and mailbox compose rather than sit as free primitives — e.g. Capacity::new(n)?.bounded::<A>() or a Mailbox::builder() — method-based, no free-floating bounded(), combinators where they genuinely fit. Principal-grade naming + cohesion.

C. Keep (this is an upgrade, not a teardown)

The #112 test net (17 tests), the criterion harness, the reproducible nix build .#mutants gate, Capacity boundary-safety, the large-variant discipline + size_of guards, and the fat-variant macro-enforcement plan (#114).

Rigor (same contract)

TDD; the 4 cross-cutting categories; proptest; mutation zero-survivors; criterion bench; god-level bar; everything reproducible via the pinned flake.

Related

Supersedes the mailbox impl from #112 / PR #132 · epic #122 · #19 (channel-handler strategy) · #55 (cancellation) · unblocks the loom/shuttle DST deferred from #112.