Phase 0+1+2+3 of custom Result<T> support — registry, seams 1 & 3, caller-side unwrap (refs #2221)

[jeremydmiller]

First slice of issue #2221, following @jeremydmiller's design plan posted there. Implements the in-process mediator portion end-to-end: the registry, seams 1 & 3, and the caller-side unwrap (component R). Leaves seam 2 (request/reply wire-format-is-literal-Result), HTTP (Phase 4), tiny library adapters (Phase 5), diagnostics (Phase 6), and the tutorial (Phase 7) for follow-ups, plus the two specific test scenarios noted at the bottom that need seam 2 to land cleanly.

What works end-to-end (validated)

opts.UseResultType(
    typeof(Result<>),
    stopWhen: x => ((ResultBase)x).IsFailed,
    unwrapWith: x => x.GetType().GetProperty(nameof(Result<int>.ValueOrDefault))!.GetValue(x),
    errorsFrom: x => ((ResultBase)x).Errors.Select(e => e.Message));

// Handler — feels like writing a normal MediatR-style Result handler
public static class CreateOrderHandler
{
    public static Result<OrderPlaced> Handle(CreateOrder cmd, OrdersBook book)
    {
        if (cmd.Quantity <= 0) return Result.Fail<OrderPlaced>("Quantity must be positive");
        book.Placed.Add(cmd.OrderId);
        return Result.Ok(new OrderPlaced(cmd.OrderId));
    }
}

// Caller
var placed = await bus.InvokeAsync<OrderPlaced>(new CreateOrder("o-1", 5));   // success: unwrap to OrderPlaced
await bus.InvokeAsync(new CreateOrder("o-2", 0));                              // failure: errors logged, no cascade

That's exactly the user-experience Jeremy described in the design-plan "What it looks like end-to-end" section, working today against FluentResults 3.16.0 — no library-specific code in Wolverine; the registration takes accessors as lambdas so it works against any Result library.

Architecture

Four files form the new feature surface:

Component	File	Role
Registry	Wolverine/Configuration/ResultTypeRegistry.cs + ResultTypeRegistration.cs + IResultTypeRegistration.cs	Per-host catalog. Resolves a closed handler-return type against the registered set (exact match + open-generic match), memoized hot path.
Public API	Wolverine/WolverineOptions.Results.cs	UseResultType<TResult>(...) (closed) + UseResultType(typeof(Result<>), ...) (open-generic). Idempotent: re-registering replaces; only registers the policies + DI singleton on first call.
Seam 1	Wolverine/Middleware/ResultTypeContinuationPolicy.cs	Continuation strategy mirroring RequirementResultContinuationPolicy. Detects a Before-style middleware method whose return is a registered Result type and emits an early-return frame.
Seam 3	Wolverine/Runtime/Handlers/ResultUnwrappingActionSource.cs + ResultTypeReturnActionPolicy.cs	Phase-A IHandlerPolicy walks chains and replaces the default CascadingMessageActionSource with the unwrap-and-cascade variant whenever the handler returns a registered Result type.
Component R	Wolverine/Runtime/RemoteInvocation/ReplyListener<T>.Complete	Caller-side unwrap. T == wrapper → pass-through. T == inner → unwrap on success, throw ResultFailureException on failure. Threaded via ReplyTracker so the same path serves in-process and remote callers.

One supporting change: IContinuationStrategy got an opt-in extension IRulesAwareContinuationStrategy so strategies that need to consult per-host state can receive GenerationRules. Non-breaking — existing strategies keep the rules-free overload and aren't touched.

ResultFailureException is the new top-level exception type, with Errors : IReadOnlyList<string>.

Tests + verification

Testing/CoreTests/Acceptance/result_types_end_to_end.cs against FluentResults 3.16.0:

ID	Scenario	Status
B-1	InvokeAsync<OrderPlaced>(...) against Result<OrderPlaced> success	✅ pass
B-2	Same, failure throws ResultFailureException	[Skip] — needs seam 2
B-3	InvokeAsync<Result<OrderPlaced>>(...) returns wrapper on both branches	[Skip] — needs seam 2
B-4	InvokeAsync(...) void against Result<T> success cascades inner T	✅ pass
B-5	Same, failure suppresses cascade entirely	✅ pass
B-7	Task<Result<T>> async handler unwraps normally	✅ pass
E-1	Non-Result handlers unaffected by registration (regression guard)	✅ pass

5/5 active tests pass; 2 deferred with clear follow-up notes inlined in the file. Full dotnet build wolverine.slnx -c Release clean (0 warnings, 0 errors).

Why B-2 and B-3 are deferred

Both scenarios are on the InvokeAsync<T> request/reply path. With only seam 3 substituting the chain's ReturnVariableActionSource, the reply path on a Result-returning handler either:

• Suppresses the cascade entirely on failure (no reply ever lands at the caller), or
• Unwraps before the wire on success when the caller awaited the wrapper (Result<T> never reaches component R as the literal type Jeremy's Q5 specifies).

The clean fix is exactly what Jeremy's plan table calls seam 2 — teach HandlerChain.UseForResponse to KEEP the literal wrapper on the reply path while seam 3 keeps unwrapping for fire-and-forget. That's the natural next slice and lives alongside Phase 4 (HTTP, which has the same wrapper-vs-unwrap branching against ProblemDetails) and the C-series external-transport tests. Tracking that as the immediate follow-up.

The Phase A vs Phase B ordering trap from #2941 / #2944 doesn't bite this feature: seam 1 reads the registry from GenerationRules.Properties (set at registration time), and seam 3's ResultTypeReturnActionPolicy is an IHandlerPolicy that runs eagerly during HandlerGraph.Compile — both run before any chain's lazy attribute Modify() work fires.

Following the issue's design plan

Maps to Jeremy's phase table like this:

Phase	Status
0 — Spike against SimpleResults	folded into Phase 1; spike API shape validated against FluentResults instead per scope-question answer
1 — Core registration + seam 1	✅
2 — Seam 3 (non-request/reply handler return)	✅
3 — Component R (caller-side unwrap)	✅ for happy path; B-2 / B-3 wrapper-passthrough + failure-throws need seam 2
4 — Wolverine.Http binding	follow-up
5 — Tiny adapters (UseSimpleResults(), UseFluentResults())	follow-up
6 — Diagnostics (describe-handlers annotation)	follow-up
7 — Docs / tutorial / mdsnippets	follow-up

🤖 Generated with Claude Code