Performance budget and ratchet (targets aspire, ceilings hold)

Generated from pattern-library/registry.json — do not edit by hand; change the registry and run bun run patterns:build.

Category: Velocity Measurement · Tier: deep · Maturity: proven (verified 2026-09-09 @ 921e8266-dirty) · Risk: low — measurement and gating only; no runtime behaviour

Two thresholds with different jobs: targets are where we want to be and never fail a build, ceilings are the measured value at the moment it was accepted and only ever move down. A gate wired to a target gets muted the afternoon it is added.

When to use: Use for any deterministic metric worth defending — shared JS, route JS, prerendered document weight, known expensive queries.

Docs

• docs/blueprint/velocity/measurement.md#performance-budget-and-ratchet — Targets vs ratchets, and the field/lab/dev split (GitHub · GitLab)
• docs/stack/quality/performance.md — The measurement contexts in full (GitHub · GitLab)

Code

• src/lib/server/perf/budgets.json — The single source of truth for both kinds of threshold (GitHub · GitLab)
• src/lib/server/perf/budgets.ts — Scoring, and why lab and field budgets cannot be shared (GitHub · GitLab)

Tests

• src/lib/server/perf/snapshot.gate.test.ts (GitHub · GitLab)
• src/lib/server/perf/budgets.test.ts (GitHub · GitLab)

Proof

• /showcases/observability/budgets
• /showcases/observability/honesty

Invariants

• Targets and regression gates stay distinct — a target may be red today, and saying so is the point.
• Ratchets move down, not up, except through explicit architectural review. Lowering a ceiling is how an improvement gets banked.
• Development measurements are never mixed with lab or production ones.
• A metric is only ratcheted when it is deterministic enough to be reproducible — which is why cold-start time is reported and not gated.
• A lab snapshot from a non-production build is refused rather than scored.

Emulation notes

• Give ceilings a few percent of headroom over the measurement. Set exactly at the measured value, one ordinary feature trips the gate — and a gate that fails on ordinary work is a gate that gets muted. The headroom absorbs a feature and deliberately not a heavy dependency.
• Keep the thresholds in ONE file that both the application and the shell probes read. Two copies drift, and the copy that drifts is always the one the gate uses.
• Field and lab budgets for the same metric name are different numbers. Scoring a real-user p75 against a warm-preview budget reports a failure on every healthy deployment.

Machine-readable record: performance-budget-ratchet in pattern-library/registry.json.