Hmbown/CodeWhale · error · PersistenceBacklogError

baseline_observation.

Error message

baseline_observation.{field} exceeds its ceiling

What it means

For each CEILING_FIELDS entry, validate_budget checks that the baseline_observation value does not exceed the corresponding ceilings value. The budget is a one-way ratchet: the recorded baseline must already be within its own ceiling. If any baseline number (retained_queued_requests, estimated_retained_payload_bytes, enqueue_elapsed_ns, rss_during_delta_bytes, or rss_after_delta_bytes) is above its ceiling, the budget is internally inconsistent and rejected.

Solutions

  1. Re-run the measurement to record a fresh baseline_observation, then set each ceiling >= its observed baseline value
  2. Raise the offending ceiling back to at least the baseline value in baseline_observation
  3. Regenerate the whole budget (baseline + ceilings) in one pass so they stay consistent

Example fix

// before
{ "ceilings": { "enqueue_elapsed_ns": 1000 }, "baseline_observation": { "enqueue_elapsed_ns": 2500 } }
// after
{ "ceilings": { "enqueue_elapsed_ns": 2500 }, "baseline_observation": { "enqueue_elapsed_ns": 2500 } }
Defensive patterns

Strategy: validation

Validate before calling

from check_persistence_backlog_budget import CEILING_FIELDS
for f in CEILING_FIELDS:
    assert budget["baseline_observation"][f] <= budget["ceilings"][f], f"baseline {f} exceeds its ceiling"

Type guard

def baseline_within_ceilings(b):
    c, o = b.get("ceilings"), b.get("baseline_observation")
    return isinstance(c, dict) and isinstance(o, dict) and all(o.get(f) is not None and o[f] <= c[f] for f in CEILING_FIELDS)

Try / catch

try:
    validate_budget(budget)
except PersistenceBacklogError as e:
    if "exceeds its ceiling" in str(e):
        print("re-measure a new baseline or raise the ceiling to at least the baseline")
    raise

Prevention

When it happens

Trigger: compare calls validate_budget and for some ceiling field baseline_observation[field] > ceilings[field] — typically after someone tightened a ceiling below the recorded baseline, or recorded a baseline from a different run than the ceilings were set from.

Common situations: Hand-tightening ceilings without re-measuring a new baseline; regenerating baseline_observation on a slower machine while keeping old ceilings; an earlier partial edit that moved only one of the two numbers.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/8c7f335495929419. Report an issue: GitHub.

Appendix: 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 433685b202)