feat(cmd-queue): add CommandResult.handedOff() for cross-queue re-enqueue

[pditommaso]

Summary

Adds CommandResult.handedOff() so a handler can end a command's life on its current queue and continue it on a different queue. Supports the sched monitor-stream design (seqeralabs/sched#303).

Two accompanying breaking changes remove library-level single-queue assumptions so applications can wire multiple CommandService / MessageStream instances (one per queue) without fighting default beans.

What changes

lib-cmd-queue-redis

• CommandStatus.HANDED_OFF — new non-terminal pseudo-status. Used only as a CommandResult marker; never written to CommandState.
• CommandResult.handedOff() — new factory. Signals: "I've moved this command to another queue (e.g. via otherQueue.submit(...)). ACK the source without running the normal terminal-result transition."
• CommandServiceImpl.processCommandWithHandler — one additional branch on HANDED_OFF: transition the persisted state to RUNNING (via state.started()) if it isn't already, then return true so the source is ACKed. The SUBMITTED → RUNNING transition is required so the destination queue's consumer dispatches to checkStatus() rather than re-running execute() — otherwise the non-idempotent initial work would re-fire on every poll, producing an infinite execute → handedOff loop.
• Breaking — CommandServiceImpl is no longer @Singleton. Class annotations removed and field @Injects replaced with a public constructor. Each application must now wire its own CommandService bean(s) via a @Factory. Single-queue apps declare one factory method; multi-queue apps declare one per queue, all sharing the same CommandStateStore.
• Test scaffolding: TestCommandQueueFactory now also produces the CommandService bean; new TestRedisStreamConfig provides the config bean required by the new @EachBean wiring (see below).

lib-data-stream-redis (bumped to 1.4.0)

• Breaking — RedisMessageStream and LocalMessageStream are no longer auto-registered beans. All Micronaut class-level annotations (@Singleton, @Requires, @Inject, @PostConstruct) removed; both are now plain classes with public constructors.
• New DefaultRedisMessageStream / DefaultLocalMessageStream — thin Micronaut-managed subclasses, each annotated @EachBean(RedisStreamConfig.class) plus @Requires(bean = RedisActivator.class) / @Requires(missingBeans = RedisActivator.class) respectively. One MessageStream bean is now produced per RedisStreamConfig bean in the context, inheriting the same qualifier — so multi-queue apps declare multiple named configs (e.g. via @EachProperty) and get named streams automatically, no hand-written per-queue factories required.
• Migration — applications that previously injected MessageStream<String> unqualified must declare at least one RedisStreamConfig bean so @EachBean produces a stream.

READMEs

Both modules' READMEs updated with the breaking-change callout, migration examples, and the hand-off pattern including the idempotency caveat (non-atomic submit then ACK — handlers must tolerate replay).

Why this shape

An earlier draft proposed CommandResult.activeOnStream(dst) with an attachQueue / routing-registry / stream-name lookup inside the library. That conflated two genuinely different outcomes ("still active here" vs "done here, continue over there") and baked routing into the service. This version keeps routing out of the library entirely: handlers directly inject the target queue and call submit(...) themselves, and the framework just knows when to ACK without marking the command done.

Moving both CommandServiceImpl and the MessageStream implementations off @Singleton is the matching structural change: the previous class-level bean annotations encoded a one-queue-per-app assumption that has to be relaxed for hand-off to make sense.

Handler usage

@Inject @Named("monitor") CommandQueue monitorQueue;

@Override
public CommandResult<MyResult> execute(Command<MyParams> command) {
    backend.launch(...);
    monitorQueue.submit(CommandMsg.of(command.id(), command.type()));
    return CommandResult.handedOff();
}

Idempotency contract

Hand-off is not atomic — the destination submit happens before the source ACK. If the consumer crashes between the two, the source is redelivered and the handler runs again. Handlers must tolerate replay, typically by persisting an intermediate state before non-idempotent side-effects so the replay can skip them. On the destination side, the SUBMITTED → RUNNING transition performed by the framework ensures subsequent consumer passes dispatch to checkStatus() rather than re-invoking execute().

Test plan

• New CommandResultHandedOffTest covers: handedOff() produces a non-terminal HANDED_OFF result; HANDED_OFF is not terminal; only SUCCEEDED / FAILED / CANCELLED are terminal; state.started() correctly drives SUBMITTED → RUNNING before ACK.
• Existing test suites pass (:lib-cmd-queue-redis:test, :lib-data-stream-redis:test) after the DI reshape, with TestCommandQueueFactory and TestRedisStreamConfig providing the beans the library no longer self-registers.
• Integration verification in the downstream sched PR: two CommandService beans wired from named RedisStreamConfigs, handlers registered on both, hand-off routes correctly.

🤖 Generated with Claude Code