feat: add fair-share admission control

[tisonkun]

Summary

• introduce mea::admission as the problem-domain module and FairShare as its concrete work-conserving policy
• bound global concurrency while selecting the queued key with the fewest held permits, using queue order to break ties
• expose only available_permits for state observation and keep queue depth, per-key usage, and idle bookkeeping private
• align borrowed and owned permit documentation with the corresponding Semaphore types, including acquire/try entry points and drop behavior
• organize waiters as per-key FIFO queues backed by a slab, so scheduling scans contending keys instead of every queued acquisition
• cover fair distribution, tie ordering, cancellation before and after admission, owned permits, custom hash builders, Send futures, and permit-limit stress

This supersedes #114. It preserves the intended scheduling behavior, but deliberately replaces the semaphore-oriented API and flat waiter queue with an admission-domain design.

Verification

• cargo x test
• cargo x lint
• RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
• cargo +1.85.0 check --workspace --all-targets --all-features
• cargo package -p mea --allow-dirty

[Copilot]

Pull request overview

This PR introduces a new admission-control domain module (mea::admission) with a concrete work-conserving policy (FairShare) to bound global concurrency while fairly distributing permits across contending keys.

Changes:

• Add mea::admission::FairShare with borrowed + owned permits, keyed FIFO wait queues, and fairness based on fewest in-flight permits (queue order as tie-breaker).
• Expose observability helpers (capacity, available_permits, queue_len, in_flight, is_idle) and integrate the module into crate docs/public API.
• Add comprehensive tests covering fairness, ordering, cancellation behavior, owned permits, Send futures, custom hashers, and stress capacity.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Documents the new admission::FairShare feature and positions it among existing primitives.
mea/src/lib.rs	Exposes the new admission module publicly and adds Send/Sync/Unpin assertions for the new types.
mea/src/admission/mod.rs	Defines the admission domain module and re-exports FairShare and permit types.
mea/src/admission/fair_share.rs	Implements the FairShare admission controller, permits, waiter scheduling, and cancellation behavior.
mea/src/admission/tests.rs	Adds targeted unit and stress tests validating fairness, ordering, cancellation, and Send behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.