Hmbown/CodeWhale · error · PersistenceBacklogError

baseline_observation.{field} exceeds its ceiling

Error message

baseline_observation.{field} exceeds its ceiling

What it means

Raised by validate_budget() when a baseline_observation value for one of the five CEILING_FIELDS (retained_queued_requests, estimated_retained_payload_bytes, enqueue_elapsed_ns, rss_during_delta_bytes, rss_after_delta_bytes) exceeds the ceiling recorded for the same field in ceilings. The budget is self-consistent by construction - ceilings are one-way upper bounds set at or above the baseline - so this mismatch means the two blocks were edited independently.

Source

Thrown at scripts/check-persistence-backlog-budget.py:267

        raise PersistenceBacklogError("budget fixture no longer matches the frozen workload")
    for field, expected in FIXTURE.items():
        if type(fixture[field]) is not type(expected) or fixture[field] != expected:
            raise PersistenceBacklogError(
                f"budget fixture.{field} must remain {expected!r}"
            )
    if budget.get("baseline_receipt") != BASELINE_RECEIPT_REFERENCE:
        raise PersistenceBacklogError("budget baseline_receipt path changed")
    ceilings = budget.get("ceilings")
    baseline = budget.get("baseline_observation")
    if not isinstance(ceilings, dict) or not isinstance(baseline, dict):
        raise PersistenceBacklogError("budget needs ceilings and baseline_observation objects")
    for field in CEILING_FIELDS:
        ceiling = non_negative_integer(ceilings.get(field), f"ceilings.{field}")
        observed = non_negative_integer(
            baseline.get(field), f"baseline_observation.{field}"
        )
        if observed > ceiling:
            raise PersistenceBacklogError(
                f"baseline_observation.{field} exceeds its ceiling"
            )
    baseline_accepted = non_negative_integer(
        baseline.get("accepted_requests"), "baseline_observation.accepted_requests"
    )
    if baseline_accepted != FIXTURE["requests_attempted"]:
        raise PersistenceBacklogError(
            "baseline_observation.accepted_requests must equal requests_attempted"
        )
    baseline_applied = non_negative_integer(
        baseline.get("applied_version"), "baseline_observation.applied_version"
    )
    if baseline_applied != FIXTURE["expected_applied_version"]:
        raise PersistenceBacklogError(
            "baseline_observation.applied_version must be the final sent version"
        )
    baseline_retained = baseline["retained_queued_requests"]
    baseline_payload = baseline["estimated_retained_payload_bytes"]

View on GitHub (pinned to 8880682c63)

Solutions

1. Make ceilings[field] >= baseline_observation[field] for all five fields
2. When tightening ceilings, lower them only down to the baseline, never below it
3. For a genuine new baseline, re-run the macOS measurement on a clean tree and regenerate budget and baseline receipt together

Example fix

// before (budget.json)
"baseline_observation": { "enqueue_elapsed_ns": 456170, ... },
"ceilings": { "enqueue_elapsed_ns": 400000, ... }

// after: ceiling back at/above the frozen baseline
"baseline_observation": { "enqueue_elapsed_ns": 456170, ... },
"ceilings": { "enqueue_elapsed_ns": 25000000, ... }

CEILING_FIELDS = ("retained_queued_requests", "estimated_retained_payload_bytes",
                  "enqueue_elapsed_ns", "rss_during_delta_bytes", "rss_after_delta_bytes")

def ceilings_cover_baseline(budget: dict) -> bool:
    ceilings = budget.get("ceilings", {})
    baseline = budget.get("baseline_observation", {})
    return all(
        baseline.get(f, float("inf")) <= ceilings.get(f, -1)
        for f in CEILING_FIELDS
    )

try:
    increases, decreases = compare(receipt, budget)
except PersistenceBacklogError as error:
    print(f"[persistence-backlog-budget] ERROR: {error}", file=sys.stderr)
    raise SystemExit(2) from error

When it happens

Trigger: Tightening ceilings below the frozen baseline numbers (e.g. setting estimated_retained_payload_bytes ceiling under the 8527994 baseline), or raising a baseline value without raising its ceiling.

Common situations: Someone shrinks a ceiling to force future optimization work, forgetting the baseline itself must still fit; hand-rebaselining observation numbers while leaving old ceilings; unit drift (ms vs ns) making a baseline look larger.

Related errors

• baseline_observation.retained_queued_requests exceeds accept
• baseline_observation payload is smaller than frozen retained
• rss_during_delta_bytes is inconsistent
• rss_after_delta_bytes is inconsistent
• budget document_kind must be {BUDGET_KIND}

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/8c7f335495929419. Report an issue: GitHub.