# Requirement change — a cap everybody draws on together

Per-client limits did what we asked and the database still fell over. The reason is arithmetic we
should have seen coming: we have four hundred clients, most of them on 100 a minute, and nothing
anywhere says what happens when three hundred of them are busy at the same time. Every one of them
was inside its own limits the whole way down.

So there is now a **shared ceiling on top of the per-client ones**: a total the whole estate draws on
together, and a request has to be inside its own client's limits *and* inside that.

## What it means precisely

The shared cap is **an ordinary client key** — it is not a number and not a special case. You are
handed the key at construction (`Entry.createWithBackstop(clock, backstopKey)`), and its limits are
configured through the same `configure(key, rules)` everything else goes through. That is deliberate:
it means the cap gets the whole rule vocabulary for free — several rules at once, any algorithm, a
name a denial can quote, and `reset` as an operator's release valve — rather than a second, parallel
notion of counting that would need its own window and its own retry arithmetic.

Nothing in the existing contract changes. Two of its rules now have consequences worth stating out
loud, because they are the ones people get wrong:

- **All-or-nothing spans both budgets.** If the shared cap refuses, the caller's own rules are **not**
  charged. If the caller's own rules refuse, the shared cap is **not** charged. Neither, or both.
- **The report is still the longest wait.** `deniedBy` and `retryAfter` come from whichever rule
  anywhere in the request has the longest wait. On a tie, the **shared cap's** rules are considered
  before the caller's own, and within either, the rule configured first.
- **`remaining(key)` is the tightest figure across both.** It answers "how many more would be allowed
  right now", and the cap is part of what decides that. A `remaining` that reported only the caller's
  own rules would tell somebody they had 95 left and then refuse them.
- **`reset(key)` still resets exactly one key.** Letting one caller back in does not refill the shared
  cap, and clearing the shared cap does not clear anybody's own count.
- **A request made under the cap's own key draws on that budget once, not twice.**
- A caller with no rules of its own is unlimited *on its own account*. That is not the same as being
  exempt from the shared cap, and it is still capped.

## What we are not asking for

- Not a per-tenant tier in between, and not a hierarchy of caps. One shared key, on top of the
  caller's own. If you can see how the third one would go in, say so; do not build it.
- Not fairness, weighting, or a queue. First come, first served, and the rest are refused.
- Not a change to how any existing rule counts, and not a new algorithm.
- Not a way to exempt a caller from the cap.

## The question behind it

A request now needs **two budgets at once**, and it has to hold both for the whole of deciding *and*
charging — otherwise it can be allowed by a budget that is exhausted by the time it is charged. Two
locks held at once is where deadlocks come from. So: which locks does a request take, in what order,
who decided that order, and where is it written down?
