Hmbown/CodeWhale · error · PersistenceBacklogError

receipt {field} must remain {expected!r}, got {value!r}

Error message

receipt {field} must remain {expected!r}, got {value!r}

What it means

Raised by validate_frozen_field (scripts/check-persistence-backlog-budget.py:102-106) when a receipt's frozen fixture field differs in type or value from the FIXTURE constant. The checker pins the measurement workload (fixture_id, request_variant, payload_estimator, paused_consumer, requests_attempted=128, content_bytes_per_request=65536, single_session_id, expected_applied_version=127) plus build_profile="test" and sample_count=1, so any drift between the receipt and the checker's frozen contract aborts the gate.

Source

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

def load_json(path: Path, label: str) -> dict[str, Any]:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as error:
        raise PersistenceBacklogError(f"invalid {label} {path}: {error}") from error
    if not isinstance(value, dict):
        raise PersistenceBacklogError(f"{label} must be a JSON object")
    return value


def non_negative_integer(value: Any, field: str) -> int:
    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
        raise PersistenceBacklogError(f"{field} must be a non-negative integer")
    return value


def validate_frozen_field(field: str, value: Any, expected: Any) -> None:
    if type(value) is not type(expected) or value != expected:
        raise PersistenceBacklogError(
            f"receipt {field} must remain {expected!r}, got {value!r}"
        )


def current_source_identity() -> dict[str, Any]:
    def run(command: list[str]) -> str:
        result = subprocess.run(
            command,
            cwd=ROOT,
            text=True,
            capture_output=True,
            check=False,
        )
        if result.returncode != 0:
            raise PersistenceBacklogError(
                f"source provenance command failed: {' '.join(command)}"
            )
        return result.stdout.strip()

View on GitHub (pinned to 8880682c63)

Solutions

1. Re-run scripts/measure-persistence-backlog.py (or run the checker without --receipt so it measures fresh) to regenerate a receipt matching the current fixture.
2. If the workload change is intentional, update FIXTURE in check-persistence-backlog-budget.py, the Rust measurement test, the budget's fixture block, and the baseline receipt together in one commit.
3. Discard any manual edits to receipt JSON — receipts are provenance artifacts, not configuration.
4. Verify the receipt was produced from the same commit as the checker you are running.

Example fix

// receipt (before)
"requests_attempted": 64
// receipt (after, matches FIXTURE)
"requests_attempted": 128

import json, sys
sys.path.insert(0, "scripts")
from check_persistence_backlog_budget import FIXTURE  # or inline the constant

receipt = json.load(open("receipt.json"))
for field, expected in FIXTURE.items():
    if type(receipt.get(field)) is not type(expected) or receipt.get(field) != expected:
        sys.exit(f"stale receipt: fixture field {field} drifted; re-measure")

def fixture_matches(receipt: dict) -> bool:
    return all(
        type(receipt.get(f)) is type(exp) and receipt.get(f) == exp
        for f, exp in FIXTURE.items()
    )

try:
    validate_receipt(receipt)
except PersistenceBacklogError as e:
    if "must remain" in str(e):
        raise RuntimeError("receipt predates the current fixture; regenerate it") from e
    raise

When it happens

Trigger: Checking a --receipt JSON produced by an older/newer measurement test whose workload differs; editing FIXTURE in the checker (e.g. bumping requests_attempted) without re-measuring the receipt; hand-editing the receipt JSON; a stale baseline receipt after the Rust test's fixture changed.

Common situations: Schema/workload evolution where the Rust test and the Python checker were updated in different commits; regenerating the budget but reusing an old receipt; cherry-picking a fixture change without the matching re-measurement.

Related errors

• Codewhale terminal receipt exceeded its total bound
• Codewhale stream-json line {line_number} was not an object
• invalid {label} {path}: {error}
• {label} must be a JSON object
• {field} must be a non-negative integer

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