Track command processing errors on CommandState (errorsCount, error, modifiedAt)

[pditommaso]

Stacked on #102 (which is stacked on #100). Base is fix/cmd-queue-retry-on-handler-exception. Merge order: #100 → #102 → this.

Recovers the error tracking originally released as 0.6.0 (e54229e, #89), which #100's revert to 0.4.0 dropped. VERSION is deliberately untouched — functionality only; numbering is a separate decision.

Why this belongs with #102

#89's own changelog says it plainly: it exists because of #87. Once a thrown handler is retried instead of terminal-failed, a command can retry indefinitely with nothing recording that it is happening. #102 on its own creates that blind spot; this closes it.

• errorsCount — consecutive processing errors since the last successful processing
• modifiedAt — last-write timestamp
• error — now also carries the message of a transient (non-terminal) processing error. It holds the most recent message, transient or terminal; a terminal failure is identified by status == FAILED, not by error being non-null.

recordError is best-effort: a failed write is logged and never changes control flow, so the command is still kept in the queue and retried. The streak resets on recovery with a single write, and only when there is something to reset, so healthy re-polls stay write-free. Backward-compatible — new fields default to 0/null when older serialized state is read.

One deliberate adaptation from e54229e

Not a verbatim cherry-pick. This tree still has executeWithTimeout, which wraps a handler exception:

throw new RuntimeException("Command execution failed", e);

#89 was written against #84, which had removed that method, so the handler's exception propagated directly and recording e.getMessage() was correct there. On 0.4.x it is not: every transient error on the execute() path would be stamped with the same useless "Command execution failed", defeating the whole purpose of the field.

recordError now records the root cause's message via a small rootMessage() helper, which is also correct for the checkStatus() path where the exception propagates directly.

This was caught by #89's own test, which asserts error == 'Persistent boom' and failed with Command execution failed before the adaptation:

state.error() == 'Persistent boom'
|     Command execution failed
CommandState[... status=SUBMITTED, error=Command execution failed, errorsCount=2, modifiedAt=...]

Note the rest of the mechanism was already correct in that run — errorsCount=2, modifiedAt set, status non-terminal. Only the message needed unwrapping.

Verification

• :lib-cmd-queue-redis:test — 18 tests, 0 failures on a forced --rerun.
• Includes [release] Track command processing errors on CommandState (errorsCount, error, modifiedAt) #89's two specs (streak-and-message tracking on a still-retryable command; streak reset once a command recovers) and its CommandState serialization coverage.

🤖 Generated with Claude Code