feat(messagequeue)!: carry a structured failure across the dead-letter boundary

[behinddwalls]

Summary

Why?

Today the only thing that crosses the dead-letter boundary is a string, and on the most common path not even that.

Nack(ctx) takes no reason at all, so when a retryable error exhausts its budget the poll loop dead-letters the message with the hardcoded literal "exceeded retry limit". The error that actually caused it exists only in a log line. Reject does better — it passes err.Error() — but that is a flattened fmt.Errorf chain, so a consumer wanting to know what failed has nothing to read but prose.

That is a problem for any stage whose work is wider than the message that triggers it. Such a stage can fail because of an entity the message does not name, or because of nothing in particular, and a dead-letter reconciler has no way to tell — so it acts on the entity it does have and can terminate the wrong one.

What?

A failure now travels as data. platform/base/failure defines Failure{Message, Subjects, Detail}, where a Subject{Type, ID} names an entity the failure is about. Types are domain-chosen, so the platform stays domain-agnostic. A failure is always about something: when no single record is at fault the subject is the wider thing that is, which leaves an empty subject list to mean "unattributed" rather than "nothing was to blame".

The pieces:

• errs.Attribute / errs.Detail attach subjects and context to an error; errs.Attribution reads them back, merging across layers. The wrapper implements Unwrap and is neither a userError nor an infraError, so classification walks straight through it and retryability is unchanged.
• Nack and Reject take a Failure, and Delivery.Failure() returns the one recorded against a dead-lettered message.
• The consumer builds the failure from the error the controller returned, defaulting the message to err.Error(). A controller that attributes nothing produces exactly what callers sent before, which is what makes this change behaviour-neutral.
• Nack also dead-letters directly once the retry budget is spent, so the attempt still holding the reason is the one that records it. The poll-time check stays as a backstop for a delivery that never reaches Nack — a crash, or a visibility timeout — and that path keeps the generic literal. Message count is unchanged: at attempt N the next poll would have dead-lettered iff N >= MaxAttempts, which is the condition Nack now applies.

Storage splits the failure across two columns of queue_messages. last_error keeps the human-readable message, unchanged in meaning, so nothing has to decode it and SELECT last_error stays useful. A new failure_detail JSON column holds subjects and detail. The split is what makes the round trip unambiguous — one column would force a decoder to guess whether the text is an envelope or a message, and any error whose text happened to be valid JSON would decode as a malformed envelope and lose the message. An absent failure_detail means unattributed, with no heuristic involved, which is exactly the state of rows written before this column existed and of the retry-limit backstop.

failure_detail is nullable rather than taking an empty sentinel like its neighbours: a JSON column rejects ''. MoveToDLQ binds SQL NULL explicitly instead of a nil []byte, so the value does not depend on driver conversion.

No behaviour changes for any existing caller. This is the mechanism a follow-up uses to attribute speculation failures and stop them stranding a queue.

Test Plan

✅ bazel test //platform/... //submitqueue/... //runway/... //stovepipe/...
✅ bazel test //test/integration/extension/messagequeue/...
✅ make lint check-tidy check-gazelle check-mocks

New coverage:

• platform/base/failure — codec round trip including nested detail, and the float64 number-decoding behaviour pinned so it cannot surprise a caller later.
• platform/errs — the regression that matters: errors.As still reaches a wrapped driver error through the envelope, and a classifier still marks it retryable. Had the wrapper broken the chain walk, every storage error would have silently stopped being retryable.
• platform/extension/messagequeue/mysql — the nack-time dead-letter boundary as a table (budget remaining, one attempt left, final attempt, single-attempt budget, unset budget), because dead-lettering one attempt early would silently cost every message a retry.
• platform/consumer — an unattributed controller error yields a message-only failure, proving behaviour-neutrality.
• Integration — the DLQ test previously asserted dlq.last_error == "exceeded retry limit"; it now asserts the real reason from the final nack, and that the subject survives the round trip.

Issue

Part of CODEM-428

Issues