Outbox DI-registration hardening + heterogeneous-engine semantics (3.2.1)

[JasonMWebb]

Summary

Behavior-only bug-fix release (3.2.1) that closes three defects a third party hit while adopting the 3.2.0 outbox, plus a worked modular example, an integration test pinning multi-datastore transaction semantics, and documentation. No public API changes — upgrading from 3.2.0 requires no code changes.

All three defects share one theme: the transactional outbox registered its load-bearing services with TryAdd, so under realistic composition (modular apps, multiple datastores, split producer/processor hosts) the outbox silently lost durable events — no exception, no warning.

What's fixed

#15 — silent data loss under modular / multi-datastore composition (High)

WithEventTracking runs at the end of every WithPersistence call and TryAdds the in-memory IEntityEventTracker. If a non-outbox module (or a second datastore) registered first, it pinned the in-memory tracker and the outbox's own TryAdd no-opped, so every durable event dispatched in-process and was never written to the outbox.

Fix: the outbox now registers IEntityEventTracker/IEventRouter authoritatively (remove-then-add) in the shared outbox core, so it wins regardless of registration order. OutboxEntityEventTracker is a strict superset of the in-memory tracker, so it's always correct for it to win.

#16 — processor / combined hosts silently dropped durable events (Medium)

Outbox routing was registered only by AddOutboxProducer; a host that ran the poller (AddOutboxProcessor) and also committed domain entities lost its durable events.

Fix: routing moved into the shared core that both AddOutboxProducer and AddOutboxProcessor call. This also removes the registration path that could surface as an "unable to resolve InMemoryEntityEventTracker" DI error.

#15 diagnostic — routing diagnostic inspected the wrong service

OutboxRoutingDiagnosticsHostedService checked IEventRouter (which the core always binds to the in-memory router), so it false-warned on every working outbox host and missed the real failure. It now inspects the load-bearing IEntityEventTracker.

#17 — changelog/spec described unshipped features (docs)

Outbox metrics Meter, IOutboxPayloadProtector, and the deserialization allow-list (AC-18/19/20) were listed as shipped in the 3.2.0 changelog but never shipped. Moved to an explicit "Planned — not shipped in 3.2.0" note (live + versioned snapshot) with interim workarounds, and marked DEFERRED throughout the spec.

Heterogeneous-engine transaction semantics (follow-up from adopter review)

The adopter's production topology spans two engines (Postgres + SQL Server) in one composition and asked whether UnitOfWork.CommitAsync forces cross-datastore 2PC. Confirmed empirically and documented:

• An outbox row is atomic with its own datastore's state change (co-location — one connection, one local transaction).
• UnitOfWork wraps a single TransactionScope(Required), so writing a second datastore in one UoW promotes to a distributed transaction and fails loud (reproduced: TransactionAbortedException → Postgres 55000: prepared transactions are disabled). The trigger is the second connection, not the engine pairing.
• The contract: no cross-datastore atomicity; split multi-datastore operations into a unit of work per datastore; cross-datastore delivery is eventual (at-least-once via the poller).

Added

• Examples.EventHandling.Outbox.Modular — three bounded-context modules (Ordering/Billing/Shipping), each its own datastore + native outbox, composed at one root; runnable Program + end-to-end test proving every datastore persists regardless of module order.
• MultiDataStoreUnitOfWorkSemanticsTests (integration) — asserts the single-UoW-across-datastores failure and the per-datastore-scope success path.
• Regression tests: ReproOutboxModularDiTests (Feature/dapper orm support #15), ProcessorOnlyHostDiTests (Multitenancy Support #16).
• Docs: 3.2.1 changelog, "Upgrading to 3.2.1" migration note, and a "One transaction per datastore — no cross-datastore atomicity" caution in the recipes guide.

Verification

• Unit (fast lane): Persistence 453 · Core 575 · EfCore 158 · Entities 236 · Wolverine.Outbox 9 · Dapper 92 · Linq2Db 73 — all green.
• Examples (whole solution, fast lane): all 8 projects green (incl. the Feature/dapper orm support #15/Multitenancy Support #16 repros + modular).
• Integration (Podman → Postgres/RabbitMQ): CrossDataStoreOutboxTests 2/2 · RecipeTwoBBrokerOutboxTests 2/2 · MassTransit spike 2/2 · Wolverine spike 3/3 · MultiDataStoreUnitOfWorkSemanticsTests 2/2.
• Docs: Docusaurus build clean (onBrokenLinks: throw).

Reviewed and confirmed by the reporting third party.

Note: commits are structured per concern for review; squash-merge if a single 3.2.1 commit is preferred.