--budget is documented as a hard cap three times and is not one: cores bypass it (3.15x at --budget 1000)

[nikolay-e]

--budget N is documented as a hard cap in three places and is not one. Core
fragments are placed regardless of the remaining budget, so a range whose cores
alone exceed N silently returns more than N.

Measured

diffctx . --diff 993c0fb0..a24c07af --budget N, tokens read from the CLI's own
stderr summary (o200k_base, the same encoder the budget is denominated in):

--budget	emitted	over
1000	3,150	+2,150 (3.15x)
2000	3,783	+1,783
3000	4,319	+1,319
4000	4,715	+715
5000	5,468	+468
6000	6,226	+226
8000	7,998	— (within)

The overshoot decays as the budget grows and vanishes once N exceeds the
core mass of the range — the signature of a floor that ignores the cap, not of
an off-by-one.

Where

select.rs::setup_and_select_core → place_fragment:

state.remaining_budget = state.remaining_budget.saturating_sub(frag.token_count);

saturating_sub clamps the remaining budget at zero while the fragment is
placed anyway, so cores can be admitted past exhaustion and the arithmetic
cannot even record that it happened.

Why it is a contract break, not a design choice

Three surfaces promise a cap, in the imperative:

• --help: "Treat --budget as an upper bound in o200k tokens and leave
  headroom (e.g. --budget 28000 for a 32k target)".
• README.md:85: "Hard cap in o200k_base tokens … N enforces a fixed cap".
• Python API docstring: "N = hard cap".

The --help sentence is the damaging one: it tells a user to size the flag
against a real context window. Someone targeting a 32k window with
--budget 28000 is relying on exactly the guarantee that fails here, and the
failure mode at small budgets is severe (3.15x), not marginal.

--budget 0 is documented as a strict-zero floor producing an empty selection,
and it works — so the machinery to refuse emission exists. The gap is only for
small non-zero budgets.

What correct looks like

The output already has the vocabulary for this: when the budget forces files
out, it prints

**Changed files not represented in the output (budget/selection):**

and lists them (verified on a 15-file range at --budget 4000 — 6 of 15
represented, the rest named). The honest behaviour for over-budget cores is the
same one: downshift to the excerpt/signature variant, and where even that does
not fit, drop and disclose. Silently exceeding the number the user asked for is
the one option that leaves them unable to tell.

Close condition

For every range and every N > 0, emitted tokens ≤ N; anything dropped to
achieve that is named in the disclosure section. A test pins a range whose cores
exceed a small N and asserts both halves.

Q-class: this changes selection output, so it lands with a corpus run and a
baseline decision.