[daniel-noland]

First of a stack that takes flow and NAT-mapping expiry off tokio, with no async on the workers. This PR adds only the generic crate. The next two PRs put flows and mapping reapers on it.

Why

On env-5's bare-metal gateway, per-flow tokio timers are a failure mode, not a slowdown:

• With the 5 s one-way timeout at 1M flows, about 600k timer re-arms per second land on the shared 128-thread mgmt runtime. That convoys its locks, BGP drops, and the gateway leaves the network: steady state falls to 0.06 Mpps.
• An expiry storm of 1M flows causes a ~7 s outage.
• The gateway cannot sustain even 0.25 M new flows/s.

A synchronous per-worker wheel removes all three. Details are in the env-5 notes (SUMMARY.md, E1-E3) and can be shared.

Design (timer-wheel/)

• One level: WheelConfig::standard() is 10 ms × 8192 slots. Longer deadlines wrap and are revisited.
• Storage: entries live in a slab with an intrusive doubly linked list per bucket. Insert, cancel and move are O(1), with no allocation per entry. A TimerId carries a generation, so a stale cancel is a no-op.
• Lazy deadlines: the payload reports its current deadline when it comes due. A refresh therefore costs the wheel nothing; a later deadline just re-links the entry.
• Bounded sweeps: sweep(now, budget, &mut out) looks at most budget due entries and hands back Fired::{Due, Cancelled} in a batch. An avalanche of expiries cannot stall a worker's rx polling.
• Cross-thread: TimerRef::cancel and Remote::schedule go through mutex-guarded queues from the concurrency facade, so they also run under shuttle and loom. Cross-thread traffic is rare: invalidations, and config apply.
• Tests: a bolero model test against a reference model, and a cross-thread concurrency::test.

The stack

1. this PR: the crate;
2. flows expire on the worker's wheel;
3. masquerade mapping reapers on the wheel.

Further up, flow-state layout PRs make use of it. A docs PR is still to come.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 92.98597% with 35 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
timer-wheel/src/lib.rs	87.24%	13 Missing and 12 partials ⚠️
timer-wheel/src/config.rs	78.57%	6 Missing ⚠️
timer-wheel/src/queue.rs	90.90%	3 Missing ⚠️
timer-wheel/src/tests.rs	99.58%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[daniel-noland]

Closed in favor of #2004.