Explicit transactional DbContext selection for multi-DbContext handlers (supersedes #3284)

[jeremydmiller]

Supersedes #3284 (by @KhaledZaabat, preserved as a co-author). Same core need — let a handler that depends on more than one DbContext say which one is transactional — but reworked to be explicit only, no magic, per review.

Problem

A handler / HTTP endpoint / gRPC endpoint can legitimately depend on two DbContext-shaped services: one it writes through (must be enrolled in the transaction + outbox) and one it only reads from. EFCorePersistenceFrameProvider used to throw the moment it saw a second one, with no way to disambiguate.

Solution — explicit designation, no inference

Two equivalent, EF-Core-agnostic markers designate the transactional context:

• [Transactional(typeof(MyDbContext))] — carried as a chain tag. The attribute lives in the core Wolverine assembly and only stores a System.Type, so neither it nor your handler assembly references EF Core.
• [Storage(typeof(MyDbContext))] — the provider-agnostic storage attribute (the same one used for Marten/Polecat ancillary stores), now taught to designate an EF Core DbContext via a new EFCoreDbContextStorageFrameProvider (IAncillaryStoreFrameProvider). It's read directly off the handler so it's honored even under AutoApplyTransactions, whose policy runs before AncillaryStoreType is populated.

Either may name a concrete DbContext or a registered abstraction (WithDbContextAbstraction<TAbstraction, TDbContext>()), so Clean Architecture handlers never touch the concrete EF type.

When a chain has >1 DbContext and no designation, Wolverine fails fast at startup:

Cannot determine the DbContext type for <handler>, multiple DbContext types detected: … Wolverine will not guess which one owns the transaction. Either remove the automatic transactional middleware from this handler (e.g. with [NonTransactional] or by not calling AutoApplyTransactions), or explicitly designate the transactional DbContext with [Transactional(typeof(YourDbContext))] or [Storage(typeof(YourDbContext))] on the handler.

A designation naming a type the chain doesn't actually depend on also fails loudly.

What changed vs #3284

• Kept the [Transactional(typeof(X))] tag mechanism and its tests (transactional_dbcontext_selection_tests.cs).
• Dropped the registration-side WithTransactionalDbContext<T>() selection and the automatic "single Wolverine-enabled candidate" inference — that's the "magic" the review asked to remove.
• Added [Storage(typeof(X))] support + the ambiguity-validation test (storage_dbcontext_selection_tests.cs).
• Docs: new "Selecting the Transactional DbContext" section (applies uniformly to message/HTTP/gRPC) + a cross-link from Auto-Apply.

Verification (local, net9.0, Postgres + SQL Server)

• transactional_dbcontext_selection_tests (3) + storage_dbcontext_selection_tests (3): 6/6.
• transaction_middleware_mode_tests: 8/8.
• Full EfCoreTests: 183/186; the 3 stragglers are pre-existing environmental flakiness (verified: one passes in isolation, one fails on clean main, one flakes) — none touch DbContext selection.
• Release builds of Wolverine + Wolverine.EntityFrameworkCore clean.

Closing #3284 in favor of this. Full credit to @KhaledZaabat.

🤖 Generated with Claude Code