fix(blocks): report frames blocksd declines as declined, not delivered

[hyperb1iss]

Held as a draft until 0.7.0 ships. It is ready for review now.

When blocksd declined a frame, the Blocks backend logged it at debug level and returned success, so the output pipeline counted a frame the device never took as delivered. Blocks was the one backend whose acknowledgement said something untrue, and Spec 85's cut receipts need every backend's acknowledgement to be authoritative. After this PR, a decline is its own outcome: it is never counted as delivered, never counted as a failure, never disconnects the device, and the next frame goes out normally.

💡 What changes

• A new delivery outcome. The driver API gains Declined in its write outcome and delivery status, plus DeviceDeliveryAck::declined (transport started, zero bytes completed, no error). The API had no way to say "the device refused this one frame" before: a write could only be sent, suppressed, or failed, and the only retryable error, Timeout, would have been untrue.
• Blocks reports it. Every Blocks frame write returns sent, declined, or an error through one private helper, and the queue receives the decline through write_colors_shared_outcome. On the binary grid path, 0x01 is accepted and 0x00 is declined, matching blocksd (blocksd/api/server.py:204) and Spec 30; any other byte is a protocol error that takes the existing reconnect path. The key-frame path already validated a JSON acknowledgement and now maps a refusal the same way.
• The output queue counts it separately. A decline increments a new transport_declined counter and leaves frames_sent, transport_failed, errors_total, last_error, and every failure streak alone, so device lifecycle never sees it. A frame after a decline goes out even if it is identical, and replacing a declined frame is not counted as a dropped frame.
• Telemetry shows it. The device_metrics WebSocket topic and the /diagnose device output item both carry transport_declined, defaulted so older payloads decode; the OpenAPI schema marks it optional and the regenerated Python model types it int | Unset.

🎯 Behavior to know about

In a static scene, the existing retry for failed frames now also re-sends a declined frame, at the normal render cadence (Blocks stays capped at 25 FPS). Before, a declined frame was counted as delivered and never retried. No sleeps, backoff, or throttling were added.

Direct writes used by identify flashes still fold a decline into success, on purpose: one deferred frame should not abort a flash, and Govee and WLED already treat suppression the same way there. Those writes bypass the delivery counters.

For Blocks, once nothing is in flight, started equals completed plus declined plus failed attempts that reached the transport, and the end-to-end test asserts it. The identity does not hold for every backend, because USB, OpenRGB, Govee, and WLED reject some attempts before any I/O, which count as failed but never as started; the field's doc states the scoped version.

🧪 Validation

• Added or updated tests
• Added or updated docs (README, AGENTS.md, relevant spec, or guide)
• just verify passes locally (Rust fmt + lint + test)
• just deny passes (required for dependency or license changes)
• just ui-test and just ui-build pass (required for crates/hypercolor-ui/)
• just sdk-lint, just sdk-check, and just sdk-build pass (required for sdk/)
• just python-verify passes (required for python/)
• just compat-check passes (required for data/drivers/vendors/*.toml)
• just docs-build passes (required for docs or README changes)
• cd docs && zola check passes (required for docs link/content changes)
• Packaging scripts were syntax-checked (required for scripts/ or packaging/)
• just e2e-build passes with the normal Servo stack (required for daemon/UI/effect integration changes)
• just e2e-build-cpu passes when validating the CPU smoke fallback
• just e2e passes against the Servo stack (required for end-to-end behavior changes; starts daemon/browser)
• Tested on real hardware, simulator, or e2e harness (describe below)

Check	Result
blocks_backend_tests	9 pass: a fake blocksd declines then accepts on the grid and key paths on one connection, and a garbage ack byte fails, disconnects, and recovers on reconnect
backend_manager_tests	103 pass, including a decline counted apart from sent and failed, an identical follow-up frame sent rather than deduped, failure streaks untouched, and the static-scene retry
End to end	the real Blocks backend behind a real output queue: after a decline, transport_declined is 1 and sent, failed, and errors are 0; after an accepted frame, frames_sent is 1
Mutation checks	undoing each piece of the fix in turn (Blocks reporting sent, the dedupe and retry change, the dropped-frame change, unknown bytes as a decline) fails the new tests
Daemon device_metrics_tests, ws_protocol_tests, openapi_tests, rest_wire_contract_tests	pass, single-threaded
just python-verify, just python-generate-check	pass (151 Python tests)
Clippy -D warnings --all-targets (types with schema, core, daemon), cargo check --workspace, rustfmt	pass

An independent review traced every path from a Blocks write to the counters, lifecycle, telemetry, and /diagnose, and confirmed the protocol mapping against blocksd's source and Spec 30. It found no defect; the socket fixtures and fresh builds it could not run in its sandbox were run separately and pass.

🔍 Review focus

• output_queue.rs accounting and the retry predicate. A decline must stay out of every success and failure counter while still making the frame eligible to go out again.
• Exhaustive handling of Declined. Display output treats it as a protocol failure, the same boundary it already applies to a suppressed acknowledgement; Blocks has no display path.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}