{"record":{"id":"e9b0009557f1b9fa","repo":"Hmbown/CodeWhale","slug":"the-paused-channel-must-retain-the-newest-request","errorCode":null,"errorMessage":"the paused channel must retain the newest request and its payload","messagePattern":"the paused channel must retain the newest request and its payload","errorType":"exception","errorClass":"PersistenceBacklogError","httpStatus":null,"severity":"error","filePath":"scripts/check-persistence-backlog-budget.py","lineNumber":197,"sourceCode":"    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\")\n\n    limitations = receipt[\"limitations\"]\n    if not isinstance(limitations, list) or not limitations or not all(\n        isinstance(item, str) and item for item in limitations","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-persistence-backlog-budget.py#L179-L215","documentation":"Raised in validate_receipt (scripts/check-persistence-backlog-budget.py:196-199) when retained_queued_requests == 0 or estimated_retained_payload_bytes == 0. The fixture's whole premise is a paused consumer that still holds the newest request and its payload, so a zero on either side means the measurement did not actually exercise a paused backlog.","triggerScenarios":"The consumer not being paused (queue drained) when the final request was sent; the payload estimator (retained-saved-session-json-bytes-v1) returning 0 because the session JSON was empty or the estimator read the wrong field; measurement aborting before the pause phase.","commonSituations":"Pause/apply sequencing broken by an actor refactor; estimator broken after the serialized session format changed; test ordering issues under --test-threads=1 changes.","solutions":["Ensure the measurement test pauses the consumer before the final request is enqueued, then re-measure.","Fix the payload estimator to compute the retained saved-session JSON byte count, not zero.","Check the receipt's retained_queued_requests and estimated_retained_payload_bytes to see which side is zero before digging into the test."],"exampleFix":"// receipt (before)\n\"retained_queued_requests\": 0, \"estimated_retained_payload_bytes\": 0\n// receipt (after)\n\"retained_queued_requests\": 128, \"estimated_retained_payload_bytes\": 8388608","handlingStrategy":"validation","validationCode":"if receipt[\"retained_queued_requests\"] == 0 or receipt[\"estimated_retained_payload_bytes\"] == 0:\n    sys.exit(\"paused retention not exercised; verify pause ordering and the payload estimator\")","typeGuard":null,"tryCatchPattern":"try:\n    validate_receipt(receipt)\nexcept PersistenceBacklogError as e:\n    if \"must retain the newest request\" in str(e):\n        raise RuntimeError(\"queue drained or estimator zero; fix test sequencing\") from e\n    raise","preventionTips":["Pause the consumer before enqueueing the final request.","Unit-test the retained-saved-session-json-bytes-v1 estimator against a known payload.","Fail the Rust test early if either retained metric is zero."],"tags":["measurement","validation","invariants"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}