Actionable diagnostic for a header-identified saga over gRPC (GH-3385)

[jeremydmiller]

Closes #3385. For 6.18.0. Follows @erikshafer's analysis on the issue — thank you for the legwork, including the #3386 coverage this builds on.

What is NOT changing

A header-identified saga still cannot work over a gRPC hop. The saga-id envelope header is not propagated across the call, so no id can be resolved.

Per @erikshafer's framing, full three-point saga-id propagation is deliberately not taken: message-identified sagas already work over gRPC (proven by the merged #3386, documented in #3389), and the header path is a transport concern that HTTP does not exercise either — so "works like HTTP" is already satisfied. That stays a future option, not a debt.

What IS changing: the diagnostic

Before:

StatusCode.Internal — "Could not determine a valid saga state id for Envelope ..."

True, but it names no cause and no remedy — and the remedy is not guessable, because the reason the id is missing is a property of the transport, not of the message in front of you.

After:

StatusCode.InvalidArgument — "Could not determine a saga id for this request. A saga started or continued over a gRPC hop must carry its identity ON THE MESSAGE BODY: the 'saga-id' envelope header is not propagated across a gRPC call, so a header-identified saga cannot work over gRPC. Put the saga identity on the request message itself (a property Wolverine can match to the saga id, or one marked with [SagaIdentity]). See https://wolverinefx.net/guide/grpc/sagas.html"

InvalidArgument rather than Internal is deliberate (AIP-193): the request cannot succeed as sent and retrying will not change that. It is a caller-side contract problem, not a transient server fault — and Internal actively invites a client to retry something that can never work.

Where it lives

WolverineGrpcExceptionMapper, which only runs at the gRPC adapter boundary. The core IndeterminateSagaStateIdException is untouched, so non-gRPC users see no change and no gRPC-specific wording leaks into the framework's general saga errors.

Verification

• Flips the gRPC saga coverage: message-identified sagas work like HTTP; header-identified gap pinned (refs #3385) #3386 characterization test (..._fails_with_opaque_status_today → ..._fails_with_an_actionable_diagnostic), now pinning the status code, the cause, the remedy, and the docs link.
• Full Wolverine.Grpc.Tests 273/273 — the mapper is shared, so the whole suite matters here, not just the saga tests.
• gRPC + Sagas docs page updated with the new behavior and the AIP-193 rationale.
• Full wolverine.slnx Release build clean.

🤖 Generated with Claude Code