Handler outcomes

Success, retry, skip, revoke, snooze, undecodable, rate-limited, and lease-lost.

Outcomes are explicit because they have different retry, accounting, history, and retention semantics.

Outcome	Attempt consumed	Result
success	Yes, current attempt ran	Complete and retain/delete by policy
retry	Yes	Schedule deterministic backoff
skip	No additional failure	Archive without another retry
revoke	No additional failure	Delete
snooze	No	Schedule for a handler-selected delay
rate_limited	No	Requeue as a non-failure
undecodable	No retry can fix it	Park visibly
lease_lost	Counts as crash, not returned error	Reclaim or quarantine

Rust

return Err(headgate::Control::Snooze(Duration::from_secs(30)).into());
return Err(headgate::Control::RateLimited.into());
return Err(headgate::Control::Skip.into());

archived is Headgate’s dead-letter queue. See the dead-letter queue guide for inspection, redrive, notifications, and retention.