Fix Mocha saga fault handling so OnReplyFault fires

[alisan3]

Problem

When a saga dispatches a command with .Send(...) and that command's consumer fails terminally, the saga is never notified. OnFault() never fires, so the saga waits in its send state until its timeout, or forever if none is configured. The failure is invisible: nothing is logged, nothing is dead-lettered, and the payload is discarded.

Reproduced on main against the in-memory transport, so this is not transport specific.

Root cause

Three defects, the first two each independently sufficient.

1. The fault reply carried no headers. ReceiveFaultMiddleware.ReplyToSenderAsync was a hand-rolled copy of DefaultMessageBus.ReplyAsync that never adopted the header-copying contract the success path uses through TryCreateResponseOptions. The saga-id header stamped by the saga's send activity was dropped, so the reply could not be correlated back to the saga.

2. OnFault registered the wrong route kind. It went through OnEvent, producing a subscribe route bound to the saga's own endpoint. Fault replies are dispatched point to point to the shared reply endpoint, so the route could never select them. Nothing publishes a NotAcknowledgedEvent either, so that subscription could not fire in any configuration.

3. Unclaimed replies were discarded silently. ReplyConsumer threw PromiseNotFound, caught its own exception, and handed it to SetException, which is a no-op when no promise exists. That is why the failure produced no signal at all.

Changes

Collapse the duplicate reply path. TryCreateResponseOptions only ever read IMessageContext members, so it now accepts one, letting the fault middleware reuse it and dispatch through IMessageBus.ReplyAsync. ReplyOptions gains a MessageKind so the fault path keeps its own kind instead of forking the dispatch code. This removes the reply-endpoint lookup and pooled DispatchContext handling from the middleware, leaving one reply-dispatch implementation.

Bind saga fault transitions to the reply route. OnFault now registers through OnReply instead of OnEvent, so it becomes a saga-id gated reply route alongside OnReply and OnAnyReply and needs no dedicated machinery. The signature is unchanged; only the body and the documentation differ from main.

Reject OnAnyReply without a fault transition. A fault reply also satisfies OnAnyReply, whose transition is keyed on object, NotAcknowledgedEvent's base type, so a state declaring only OnAnyReply would transition as though a failed step had succeeded. This is rejected at initialization rather than resolved at runtime, so neither the routing conditions nor the transition lookup need a special case for faults. DuringAny().OnFault() satisfies it for the whole machine.

Return the pooled dispatch context after a successful reply. ReplyAsync returned its pooled DispatchContext only from a catch, so a reply that succeeded never gave it back and every reply allocated a fresh context. The five sibling operations on the bus all use finally. Pre-existing, but this branch routes fault replies through ReplyAsync too, so it sends more traffic through the defect. finally does not catch, so the exception still reaches the caller exactly as it did when the catch rethrew it.

Report unclaimed replies. A reply is expected to complete no promise whenever a saga route owns it, so the warning is raised only when ReplyConsumer is the sole consumer selected for the message. SetException now reports whether it matched a promise, mirroring CompletePromise.

Breaking changes

DeferredResponseManager.SetException returns bool instead of void. Source compatible, binary breaking.

No saga API is renamed. An earlier revision of this branch renamed OnFault to OnReplyFault; that was reverted, because the extensions layer names concepts over the core descriptor's channel-level primitives (OnTimeout is OnRequest<SagaTimedOutEvent>, not OnRequestTimeout), and because not covering publish is a missing feature rather than a naming boundary.

Verification

Mocha.Tests 4040/4040, Mocha.Sagas.Tests 620, Mocha.Transport.InMemory.Tests 792/792, Postgres and RabbitMQ topology suites green.

Each fix was checked against the code it replaces: reverting the fault middleware alone fails the header-propagation test 4/4, reverting the reply consumer alone fails the discarded-reply test with no warning written, and reverting the pooling fix alone fails the pooling test with 2 contexts rented against 1 returned. The exception-path test for ReplyAsync passes against the old code as well, which is what makes it evidence that only the success path changed.

Coverage added for both command shapes on the send leg, with and without a response type, and the publish leg is characterised as currently uncovered.

Scope of OnFault

It fires when the inbound message carried a ResponseAddress, which is the real discriminator rather than the verb used. Saga .Send and RequestAsync qualify; saga .Publish and a bare bus.SendAsync do not.

Three distinct failures, only the first of which has a mechanism today:

Failure	Signal	Reaches the saga
A command the saga sent fails downstream	NotAcknowledgedEvent on the reply endpoint	yes, via OnFault
A subscriber of an event the saga published fails	original envelope to the error endpoint	no
The saga's own transition throws	original envelope to the saga's error endpoint	no, and by construction it cannot notify itself

The documentation on OnFault now states both exclusions.

Follow-ups, not addressed here

• Publish fault coverage. FaultAddress is plumbed end to end through both transports but read by nothing, which is the natural channel for it. The open question is fan-in semantics when several subscribers of one event fail.
• A saga is never notified when its own transition fails terminally. State is rolled back correctly, but the saga stays in its waiting state and the message sits on an error queue with no saga-id header, since the event was published by someone else.
• ReceiveRedeliveryMiddleware skips delayed redelivery whenever a ResponseAddress is present, so saga sends get weaker retry protection than publishes, for a reason that does not apply to a saga.
• Every end-to-end test here is in-memory; a RabbitMQ saga reply/fault test would close that gap.

Saga_Should_ReceiveReply_When_SendUsedWithTypedOnReply failed twice during this work and could not be reproduced across five subsequent full runs, so it is unexplained. It reproduces on main and is not introduced here, but see #9947 for prior work on saga test flakiness.

🤖 Generated with Claude Code