[braghettos]

What it adds

Design: docs/design-capacity-model.md. Measurement: docs/configuration.md, "Capacity model, measured 2026-11-13 and 14".

• A capacity model, opt-in (Saturation.CapacityModel, off by default; needs a CPU limit of 500m or more). Over a window of 10s intervals it scales the reconciles in flight by how far CPU use is from the target: in flight × (target × limit − background) ÷ (CPU used − background), the utilization law the Horizontal Pod Autoscaler applies to replicas. Six rules keep it from moving without evidence.
• The v1.19.0 CPU pressure step stays as a veto: local capacity is the lower of the two, and a cut pulls the model down.
• A guaranteed share per controller, whenever saturation is on: a freed slot goes first to a controller under its equal share, otherwise it is lent to any controller with work. Nothing is preempted.
• Instruments so something outside the controller can size it: per-controller in-flight, waiting and arrivals, cuts, the CPU limit, CPU per reconcile, and a required-CPU estimate.

Measured on a cluster: a trade, not a win on everything

GKE, 32 workers, each Observe 20ms of CPU then a 400ms wait; bars committed before each block's first run.

500m limit (the workload saturates), five runs per arm:

Arm	CPU used	Observes/s	Mean local	Wall time per call	Cuts
governor off	99.7%	23.22	—	428ms	—
the step alone	99.3%	23.06	26.9	366ms	19
the step with the model, target 0.9	91.0%	20.02	8.9	23ms	0
the step with the model, target 0.95	92.9%	20.75	10.1	24ms	4

• It met four of the five bars and missed the throughput bar (at least 95% of the step alone's): 86.8% at the default target, 89.6% at 0.95. The user decided to ship it as that trade: about 14% less throughput for calls 16 times faster, opt-in.
• With one slot a tenth of the limit, a target between two slot levels (0.95 here) can settle on either.

1 CPU limit (the workload does not saturate: 84% ungoverned), three runs per arm: in two runs the model settled at the knee (22ms a call against 70ms, no less throughput); in the third CPU use never passed the target and it never moved. Under the target the law lowers nothing.

Not measured on a cluster: the share per controller with several controllers, slow reconciles, any provider other than the harness.

Behaviour with the option off

The model is off by default, and every existing test passes unmodified. The share per controller changes which controller gets a freed slot when several share a governor with saturation on; a single controller behaves as before.

Verification

• Each rule of the law, removed in turn, fails a test (26 mutations, all killed).
• go test -race on pkg/ratelimit, pkg/telemetry, pkg/controller, including a multi-queue stress test with a moving capacity.
• An independent review of the dispatch and queue code found two defects (a cut could pin capacity; lending was not round-robin), both fixed with the reviewer's failing tests added, and no lost slots, deadlocks or races.

Known limits

• After a cut, recovery with very slow reconciles is one doubling per evaluated window (up to 5 minutes), against the step's +1 per 2s.
• cpu.required is a lower bound while a backlog stands; read it with local.waiting.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NSM9VYtekkTV1h9dK4WxM4