{"record":{"id":"e9b0009557f1b9fa","repo":"Hmbown/CodeWhale","slug":"the-paused-channel-must-retain-the-newest-request-and-its","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":"validation","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/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/scripts/check-persistence-backlog-budget.py#L179-L215","documentation":"The paused channel must actually retain at least the newest request and its payload: both retained_queued_requests and estimated_retained_payload_bytes must be strictly positive. This prevents receipts that claim an empty backlog, which would mean the channel dropped work instead of buffering it behind the paused consumer.","triggerScenarios":"Raised by validate_receipt when receipt['retained_queued_requests'] == 0 or receipt['estimated_retained_payload_bytes'] == 0, from validate_baseline_receipt or compare.","commonSituations":"A measurement run where the channel consumed everything (consumer not actually paused); an estimator bug producing 0 bytes; a truncated or hand-edited receipt.","solutions":["Confirm the measurement actually pauses the consumer (fixture paused_consumer=true) and re-run the measurement.","Fix the payload estimator so it accounts for the retained request's serialized content.","Regenerate the receipt instead of editing retained_queued_requests or estimated_retained_payload_bytes manually."],"exampleFix":"// before\n{\"retained_queued_requests\": 0, \"estimated_retained_payload_bytes\": 0}\n// after\n{\"retained_queued_requests\": 1, \"estimated_retained_payload_bytes\": 65536}  # 64 KiB per request","handlingStrategy":"validation","validationCode":"def backlog_nonempty(receipt):\n    return receipt.get(\"retained_queued_requests\", 0) > 0 and receipt.get(\"estimated_retained_payload_bytes\", 0) > 0","typeGuard":"def is_positive_int(v):\n    return isinstance(v, int) and not isinstance(v, bool) and v > 0","tryCatchPattern":"try:\n    validate_receipt(receipt)\nexcept PersistenceBacklogError as e:\n    print(f\"receipt rejected: {e}\", file=sys.stderr)\n    sys.exit(2)","preventionTips":["Verify the consumer is genuinely paused before the send loop starts.","Smoke-test the payload estimator on a single known 64 KiB request.","Sanity-check that a paused-channel run always leaves at least one queued request."],"tags":["measurement","validation","backpressure","python"],"backgroundTag":"value-out-of-range","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}