How would you introduce a per-operation statement budget enforced by the build into a codebase that has never had one?

A statement budget is a recorded expectation, checked by the build, of how many statements an operation is allowed to execute. Introducing one into a codebase that has never had it is only partly a technical exercise. The technical part is a counter and a file. The part that decides whether it works is what happens the first ten times it fails. ## Start by measuring, not by legislating Nobody knows what the counts currently are, and a number invented in a design document will be wrong for most operations. The first step is a measurement pass: run the existing suite with the counter attached and record, per operation, the count it produces today. That produces a **baseline file** — one line per operation, checked into the repository next to the code. Two things follow immediately from having it: - The file is a **diff artifact**. A change that moves an operation's count now shows up in review as a changed line, which is most of the value before a single build has ever been failed. - Reading it once is itself the first audit. Some of the recorded numbers will be obviously wrong, and those are bugs to file, not baselines to enshrine. ## Ratchet, do not set a ceiling A single limit for everything ("no operation may exceed 20") fails in both directions: it blocks operations that honestly need more and permits a tenfold regression on operations that honestly need three. The workable rule is per-operation and directional: 1. The recorded number is the current count, optionally with a small headroom. 2. Exceeding it fails the build. 3. Coming in under it is not a failure, but the recorded number is **lowered** to match, so an improvement becomes the new ceiling and cannot silently regress later. 4. Raising a recorded number is a normal reviewable change, in the same commit as the code that needs it, with a reason. That is what makes it a ratchet rather than a wall: the codebase can only get better on this axis without someone consciously arguing otherwise. ## Budget where the count means something Not every operation should have one. | Path | Budget? | Why | |---|---|---| | A request or message handler with a fixed page size | yes | the count should be constant; a change is a real signal | | A user-facing read that grows with a page | as non-growth across two page sizes | the absolute number is arbitrary, the growth is not | | A batch job processing an input file | not as an absolute count | the count legitimately scales with the input; budget statements per item instead | | An administrative or one-off export | usually no | rare, unbounded, and a failing build here only trains people to bypass | Where the count varies with the input, the budget has to be a ratio — statements per item, or non-growth between two input sizes — or it will be widened until it means nothing. ## Design for the failure, because the failure is the product A budget check fails in front of someone who was trying to ship something else. Everything about how it fails determines whether it survives: - The message must print the statements grouped by shape, so the reader sees the multiplication rather than two integers. - It runs in the **fast** tier that engineers already run, not in a nightly job whose failures arrive detached from their cause. - It must be **deterministic**. One flaky budget teaches the team that budget failures are noise, and after that the real ones are re-run rather than read. - There must be a legitimate way out: an exemption with a named owner and a date, visible in the same file. A check with no escape hatch gets disabled globally the first time it blocks a release, and then you have nothing. ## Roll it out in the order that keeps goodwill Report-only first, over a few weeks, so the noise level is known before anything is blocked. Then enforce on new or recently touched operations while the historical ones stay report-only. Then close the gap deliberately, turning known-bad baselines into filed work rather than permanent exemptions. Enforcing everything on day one guarantees a large tranche of failures that nobody has context for, and the rational response to that is to turn the check off. ## Be explicit about what the budget is not It is a guard against a *shape* regression, and it neither measures nor guarantees performance. An operation can sit inside its budget and be the slowest thing in the system, and a well-founded increase can make an operation faster. It also cannot see production: the count in a test reflects the test's data and cache state, and the real distribution of inputs may take a path the suite never exercises. A budget in the build and a count observed in production are complements, and a team that has the first should not conclude it needs less of the second.