What causes "retained_queued_requests exceeds accepted_requests" in Hmbown/CodeWhale?

Audit the two counters in the Rust test to ensure they measure the same queue from the same side.

Hmbown/CodeWhale · error · PersistenceBacklogError

retained_queued_requests exceeds accepted_requests

Error message

retained_queued_requests exceeds accepted_requests

What it means

Raised in validate_receipt (scripts/check-persistence-backlog-budget.py:189-193) when retained_queued_requests > accepted_requests — a logically impossible count for a paused consumer. It guards against emitters that count queued items wrongly (e.g., counting send attempts instead of queued requests, double counting, or off-by-one errors).

Source

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

                    f"receipt {field} does not match the checked source"
                )
    if require_clean_source and receipt["source_dirty"]:
        raise PersistenceBacklogError("persistence measurement source tree is dirty")
    platform = receipt["platform"]
    if not isinstance(platform, str) or platform not in SUPPORTED_PLATFORMS:
        raise PersistenceBacklogError("receipt platform is unsupported")

    attempted = non_negative_integer(receipt["requests_attempted"], "requests_attempted")
    accepted = non_negative_integer(receipt["accepted_requests"], "accepted_requests")
    if accepted != attempted:
        raise PersistenceBacklogError(
            "accepted_requests must equal requests_attempted; sender rejection is not backlog improvement"
        )
    retained = non_negative_integer(
        receipt["retained_queued_requests"], "retained_queued_requests"
    )
    if retained > accepted:
        raise PersistenceBacklogError("retained_queued_requests exceeds accepted_requests")
    for field in ("estimated_retained_payload_bytes", "enqueue_elapsed_ns"):
        non_negative_integer(receipt[field], field)
    if retained == 0 or receipt["estimated_retained_payload_bytes"] == 0:
        raise PersistenceBacklogError(
            "the paused channel must retain the newest request and its payload"
        )
    minimum_payload_bytes = retained * FIXTURE["content_bytes_per_request"]
    if receipt["estimated_retained_payload_bytes"] < minimum_payload_bytes:
        raise PersistenceBacklogError(
            "estimated_retained_payload_bytes is smaller than the frozen retained content"
        )
    applied = non_negative_integer(
        receipt["applied_version"], "applied_version"
    )
    if applied != FIXTURE["expected_applied_version"]:
        raise PersistenceBacklogError("applied_version is not the final sent version")
    if receipt["final_version_applied"] is not True:
        raise PersistenceBacklogError("final_version_applied must be true")

View on GitHub (pinned to 8880682c63)

Solutions

Audit the two counters in the Rust test to ensure they measure the same queue from the same side.
Fix the retained-count instrumentation, then regenerate the receipt.
Verify accepted_requests == 128 first, since retained is compared against it.

Example fix

// receipt (before)
"accepted_requests": 128, "retained_queued_requests": 129
// receipt (after)
"accepted_requests": 128, "retained_queued_requests": 128

Defensive patterns

Strategy: validation

Validate before calling

if receipt["retained_queued_requests"] > receipt["accepted_requests"]:
    sys.exit("retained count exceeds accepted; queue instrumentation is double-counting")

Try / catch

try:
    validate_receipt(receipt)
except PersistenceBacklogError as e:
    if "retained_queued_requests exceeds" in str(e):
        raise RuntimeError("impossible retained count; audit both counters") from e
    raise

Prevention

Count accepted and retained from the same queue object in the Rust test.
Add an invariant assert (retained <= accepted) to the emitter.
Re-baseline instrumentation whenever the actor's queue internals change.

When it happens

Trigger: The measurement test counting retained items from the sender side while acceptance is counted elsewhere; a refactor of the queue instrumentation double-reporting entries; mixed units (requests vs payload chunks) in the two counters.

Common situations: Instrumentation drift after refactoring the persistence actor's internals; new test helper that recounts the channel independently.

Related errors

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