feat(racer): add standalone flow-control library

[Jordan Olshevski (jveski)]

Adds a standalone flow-control library for charged allocation, policy-driven admission, coalescing, and bounded pipes.

[Copilot]

Copilot review overview

🟡 Changes recommended

Reentrant callbacks can deadlock quota paths, and rejected zero-waiter joins leak active cohort capacity.

Review effort: Balanced
Findings: 3 · 2

Open (5)

• Read the clock before locking adaptive state · New
• Drop recycled charges after releasing the buffers lock · New
• Drop retained charges after releasing the recycler lock · New
• Reject zero-waiter cohorts before insertion · New
• Recover poisoned mutexes without disabling recycling · New

What changed in this PR

Adds a standalone flow-control crate to the racer dataplane workspace.

Changes:

• Implements quotas, charged buffers, bounded pipes, and credit windows.
• Adds adaptive admission, handoffs, hedging, and request coalescing.
• Adds comprehensive tests, documentation, and CI coverage.

File	Description
.github/​workflows/​ci.yaml	Adds production and simulation validation.
cmd/​racer-dataplane/​README.md	Documents flow-control usage and testing.
cmd/​racer-dataplane/​Cargo.lock	Locks the new crate dependencies.
cmd/​racer-dataplane/​Cargo.toml	Registers the workspace member.
cmd/​racer-dataplane/​flow/​.gitignore	Ignores local build output.
cmd/​racer-dataplane/​flow/​Cargo.toml	Defines the crate and dependencies.
cmd/​racer-dataplane/​flow/​src/​admission.rs	Implements admission and handoff mechanisms.
cmd/​racer-dataplane/​flow/​src/​coalesce.rs	Implements keyed coalescing and flight tracking.
cmd/​racer-dataplane/​flow/​src/​lib.rs	Implements quotas, buffers, and credit windows.
cmd/​racer-dataplane/​flow/​src/​pipe.rs	Implements bounded reusable kernel pipes.
cmd/​racer-dataplane/​flow/​tests/​workflows.rs	Tests public ownership and lifecycle contracts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Shutdown races and panic or callback-reentrancy paths can strand capacity or fail admission.

4 open findings

• Clone panic leaks admission counts · New
• Stop race admits charges after shutdown · New
• Backoff callback runs during mutable state borrow · New
• Reentrant rejection callback panics under mutable borrow · New

5 resolved since last review

• Drop retained charges after releasing the recycler lock
• Drop recycled charges after releasing the buffers lock
• Read the clock before locking adaptive state
• Recover poisoned mutexes without disabling recycling
• Reject zero-waiter cohorts before insertion

🧠 Review effort: Balanced

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

🟡 Changes recommended

Several Waker and entry destructors execute under active locks or RefCell borrows, allowing reentrant callbacks to deadlock or panic.

8 open findings

• Stage target waker replacement outside handoff mutex · New
• Stage hedge waker operations outside mutex · New
• Drop removed alarm after unlocking mutex · New
• Stage waker clone and drop outside cohort borrow · New
• Defer removed receiver drop until table borrow ends · New
• Stage register_drain waker operations outside owner borrow · New
• Defer removed entry destruction until owner borrow ends · New
• Invoke cloned waker after releasing queue borrows · New

2 resolved since last review

• Handle generation exhaustion to prevent stale permit success
• Avoid labeling every Unavailable error as stopped

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Coalescing insertion and key-cloning paths can violate completion and reentrancy guarantees.

2 open findings

• Replacing occupied entries bypasses quiescence and drops under borrow · New
• Cloning key during mutable borrow permits reentrant RefCell panic · New

8 resolved since last review

• Invoke cloned waker after releasing queue borrows
• Defer removed entry destruction until owner borrow ends
• Stage register_drain waker operations outside owner borrow
• Defer removed receiver drop until table borrow ends
• Stage waker clone and drop outside cohort borrow
• Drop removed alarm after unlocking mutex
• Stage hedge waker operations outside mutex
• Stage target waker replacement outside handoff mutex

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Reentrant key and waker callbacks can currently replace active work or execute while owner locks remain held.

3 open findings

• Dropping removed key while holding mutex can deadlock · New
• Unconditional insertion replaces reentrant in-flight operation · New
• Dropping replaced waker during borrow permits reentrant RefCell panic · New

2 resolved since last review

• Replacing occupied entries bypasses quiescence and drops under borrow
• Cloning key during mutable borrow permits reentrant RefCell panic

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Key-clone reentrancy can panic, and stopped pools retain inaccessible idle pipe resources.

1 open finding

• Reentrant key cloning can panic during mutable RefCell borrow · New

3 resolved since last review

• Unconditional insertion replaces reentrant in-flight operation
• Dropping removed key while holding mutex can deadlock
• Dropping replaced waker during borrow permits reentrant RefCell panic

Previously missed (1)

In code that hasn't changed since last review

Stopping without draining idle pipes leaks cached descriptors and charges

cmd/​racer-dataplane/​flow/​src/​pipe.rs:247

Checking stop before touching idle strands every pipe cached before Quotas::stop(): the quota authority cannot clear this pool, and all later acquisitions return here, so those descriptors and pipe-class charges remain live until the entire PipePool is dropped. Add a pool shutdown/stop path that drains the idle cache (and use it when stop is observed), matching the existing rule that leases dropped after stop are not recycled.

🧠 Review effort: Balanced