{"record":{"id":"f2aed7a799a6539d","repo":"Hmbown/CodeWhale","slug":"retained-queued-requests-exceeds-accepted-requests","errorCode":null,"errorMessage":"retained_queued_requests exceeds accepted_requests","messagePattern":"retained_queued_requests exceeds accepted_requests","errorType":"exception","errorClass":"PersistenceBacklogError","httpStatus":null,"severity":"error","filePath":"scripts/check-persistence-backlog-budget.py","lineNumber":193,"sourceCode":"                    f\"receipt {field} does not match the checked source\"\n                )\n    if require_clean_source and receipt[\"source_dirty\"]:\n        raise PersistenceBacklogError(\"persistence measurement source tree is dirty\")\n    platform = receipt[\"platform\"]\n    if not isinstance(platform, str) or platform not in SUPPORTED_PLATFORMS:\n        raise PersistenceBacklogError(\"receipt platform is unsupported\")\n\n    attempted = non_negative_integer(receipt[\"requests_attempted\"], \"requests_attempted\")\n    accepted = non_negative_integer(receipt[\"accepted_requests\"], \"accepted_requests\")\n    if accepted != attempted:\n        raise PersistenceBacklogError(\n            \"accepted_requests must equal requests_attempted; sender rejection is not backlog improvement\"\n        )\n    retained = non_negative_integer(\n        receipt[\"retained_queued_requests\"], \"retained_queued_requests\"\n    )\n    if retained > accepted:\n        raise PersistenceBacklogError(\"retained_queued_requests exceeds accepted_requests\")\n    for field in (\"estimated_retained_payload_bytes\", \"enqueue_elapsed_ns\"):\n        non_negative_integer(receipt[field], field)\n    if retained == 0 or receipt[\"estimated_retained_payload_bytes\"] == 0:\n        raise PersistenceBacklogError(\n            \"the paused channel must retain the newest request and its payload\"\n        )\n    minimum_payload_bytes = retained * FIXTURE[\"content_bytes_per_request\"]\n    if receipt[\"estimated_retained_payload_bytes\"] < minimum_payload_bytes:\n        raise PersistenceBacklogError(\n            \"estimated_retained_payload_bytes is smaller than the frozen retained content\"\n        )\n    applied = non_negative_integer(\n        receipt[\"applied_version\"], \"applied_version\"\n    )\n    if applied != FIXTURE[\"expected_applied_version\"]:\n        raise PersistenceBacklogError(\"applied_version is not the final sent version\")\n    if receipt[\"final_version_applied\"] is not True:\n        raise PersistenceBacklogError(\"final_version_applied must be true\")","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-persistence-backlog-budget.py#L175-L211","documentation":"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).","triggerScenarios":"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.","commonSituations":"Instrumentation drift after refactoring the persistence actor's internals; new test helper that recounts the channel independently.","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."],"exampleFix":"// receipt (before)\n\"accepted_requests\": 128, \"retained_queued_requests\": 129\n// receipt (after)\n\"accepted_requests\": 128, \"retained_queued_requests\": 128","handlingStrategy":"validation","validationCode":"if receipt[\"retained_queued_requests\"] > receipt[\"accepted_requests\"]:\n    sys.exit(\"retained count exceeds accepted; queue instrumentation is double-counting\")","typeGuard":null,"tryCatchPattern":"try:\n    validate_receipt(receipt)\nexcept PersistenceBacklogError as e:\n    if \"retained_queued_requests exceeds\" in str(e):\n        raise RuntimeError(\"impossible retained count; audit both counters\") from e\n    raise","preventionTips":["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."],"tags":["validation","measurement","invariants"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}