Merge pull request #226 from Vulthil/feature/review-fixes

Feature/review fixes

Author: Vulthil

Directory.Packages.props

@@ -28,6 +28,9 @@
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Relational" Version="$(FrameworkVersion)" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="$(FrameworkVersion)" />
     <PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="$(NpgsqlEfCoreVersion)" />
+    <!-- MySQL: Aspire/Pomelo integration on net9; the Microting fork (a Pomelo fork) fills the EF Core 10 / net10 gap until the official Pomelo/Aspire packages ship it. -->
+    <PackageVersion Include="Aspire.Pomelo.EntityFrameworkCore.MySql" Version="$(AspireVersion)" />
+    <PackageVersion Include="Microting.EntityFrameworkCore.MySql" Version="10.0.9" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Cosmos" Version="$(FrameworkVersion)" />
     <PackageVersion Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="4.14.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.9" />

docs/articles/cqrs-pipeline.md

@@ -80,7 +80,7 @@ Pipeline behaviors wrap every handler invocation, allowing you to add cross-cutt
 
 ### Validation
 
-`ValidationPipelineBehavior` runs all registered `IValidator<TCommand>` instances before the handler executes. When validation fails, it short-circuits and returns a `Result` containing a `ValidationError`:
+`ValidationPipelineBehavior` runs all registered `IValidator<TCommand>` instances before the handler executes. When validation fails it short-circuits: a command returning `Result` or `Result<T>` receives a failed result containing a `ValidationError`, while a command with any other response type throws a `ValidationException` (there is no in-band way to represent failure for a non-result response):
 
 ```csharp
 public sealed class CreateUserCommandValidator : AbstractValidator<CreateUserCommand>
@@ -102,7 +102,7 @@ No additional wiring is needed – the validator is picked up automatically from
 
 ### Transactional
 
-`TransactionalPipelineBehavior` wraps `ITransactionalCommand` handlers inside a database transaction. If the handler succeeds, the transaction commits; if it throws, the transaction rolls back.
+`TransactionalPipelineBehavior` wraps `ITransactionalCommand` handlers inside a database transaction. If the handler returns a successful `Result`, the transaction commits; if it returns a failed `Result` or throws, the transaction rolls back. (The non-generic `ITransactionalCommand` marker returns `Result` and is wrapped the same way as `ITransactionalCommand<Result>`.)
 
 ```csharp
 // Mark a command as transactional

docs/articles/domain-modeling.md

@@ -14,13 +14,10 @@
 
 ## Defining an Entity
 
-Entities are compared by identity, not by attribute values:
+Entities are compared by identity, not by attribute values. Give the identifier value equality — a `record` or `readonly record struct` — so two entities with the same id compare as equal:
 
 ```csharp
-public sealed class UserId(Guid value)
-{
-    public Guid Value { get; } = value;
-}
+public sealed record UserId(Guid Value);
 
 public sealed class User : AggregateRoot<UserId>
 {

docs/articles/inbox-pattern.md

@@ -79,7 +79,7 @@ public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
     public DbSet<InboxMessage> InboxMessages => Set<InboxMessage>();
 
     protected override void OnModelCreating(ModelBuilder modelBuilder)
-        => modelBuilder.ApplyConfiguration(new InboxMessageEntityConfiguration());
+        => modelBuilder.ApplyRelationalInbox();
 }
 ```
 
@@ -91,11 +91,11 @@ The consumer and the store must share the same scoped `DbContext` instance (the
 
 ### Cosmos store
 
-The Cosmos store is wired the same way — apply `CosmosInboxMessageEntityConfiguration` and call `AddCosmosInbox<AppDbContext>()`:
+The Cosmos store is wired the same way — apply the Cosmos mapping with `ApplyCosmosInbox()` and call `AddCosmosInbox<AppDbContext>()`:
 
 ```csharp
 protected override void OnModelCreating(ModelBuilder modelBuilder)
-    => modelBuilder.ApplyConfiguration(new CosmosInboxMessageEntityConfiguration());
+    => modelBuilder.ApplyCosmosInbox();
 ```
 
 ```csharp

docs/articles/outbox-pattern.md

@@ -8,7 +8,7 @@ The transactional outbox pattern guarantees that domain events raised by aggrega
 2. The aggregate root's event collection is cleared.
 3. A background service (`OutboxBackgroundService`) relays unprocessed outbox messages — woken immediately once the captured rows are durable (on transaction commit, or right after a non-transactional `SaveChanges` that captured domain events) for low latency, and polling on an interval as the backstop.
 4. Each message is routed by its `OutboxDestination` to the registered `IOutboxDispatcher` that handles it (in-process domain events by default, or the broker — see below).
-5. Successfully relayed messages are marked as processed; failures are retried up to the configured maximum.
+5. Successfully relayed messages are marked as processed; failures are retried up to the configured maximum, after which the message is dead-lettered — its `FailedOnUtc` timestamp is set, it is no longer relayed, and an error is logged with the last failure (the `Error` column).
 
 This guarantees **at-least-once delivery** because the event and the business data are committed atomically.
 
@@ -26,7 +26,7 @@ builder.AddDbContext<AppDbContext>(config =>
         .EnableOutboxProcessing(o =>
         {
             o.BatchSize = 10;   // Messages fetched per poll cycle
-            o.MaxRetries = 3;   // Retry limit before a message is abandoned
+            o.MaxRetries = 3;   // Retries before a message is dead-lettered
         });
 });
 ```
@@ -43,18 +43,25 @@ public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
         typeof(AppDbContext).Assembly;
 
     public DbSet<User> Users => Set<User>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+        modelBuilder.ApplyNpgsqlOutbox();
+    }
 }
 ```
 
-The `OutboxMessage` entity configuration is applied automatically by `BaseDbContext.OnModelCreating`.
+`BaseDbContext` owns the `OutboxMessages` `DbSet`; apply the provider-optimized mapping in `OnModelCreating` by calling your provider's extension — `ApplyNpgsqlOutbox()`, `ApplyMySqlOutbox()`, or `ApplyCosmosOutbox()` (as shown above). The agnostic `ApplyOutbox()` is available for custom providers.
 
 ## Outbox Processing Options
 
 | Property | Default | Description |
 |---|---|---|
 | `BatchSize` | 10 | Number of messages fetched per poll cycle |
-| `MaxRetries` | 3 | Maximum publish attempts before a message is abandoned |
-| `EnableParallelPublishing` | `false` | Publish messages in parallel within a batch |
+| `MaxRetries` | 3 | Publish attempts before a message is dead-lettered (`FailedOnUtc` set, no longer relayed) |
+| `EnableParallelPublishing` | `false` | Publish messages in parallel within a batch (each dispatch runs in its own DI scope) |
+| `MaxDegreeOfParallelism` | 4 | Maximum concurrent dispatches when `EnableParallelPublishing` is enabled |
 | `OutboxProcessingDelayInSeconds` | 2 | Base polling delay between processing cycles |
 | `MaxDelaySeconds` | 60 | Maximum back-off delay when no messages are found |
 | `EnableTracing` | `true` | Carry the originating trace identifier when publishing |
@@ -137,7 +144,7 @@ OutboxBackgroundService polls
     ↓
 OutboxProcessor deserialises & publishes via IDomainEventPublisher
     ↓
-Message marked as processed (or retried on failure)
+Message marked as processed (or retried on failure, then dead-lettered after MaxRetries)
 ```
 
 ## When to Use

docs/articles/packages/vulthil-messaging-inbox-cosmos.md

@@ -13,7 +13,7 @@ deduplication of redeliveries over **idempotent-by-design** consumer writes.
 
 ## Pattern
 
-- Your `DbContext` implements `ISaveInboxMessages` and applies `CosmosInboxMessageEntityConfiguration`
+- Your `DbContext` implements `ISaveInboxMessages` and applies the Cosmos inbox mapping via `ApplyCosmosInbox()`
 - The marker is a self-contained document keyed + partitioned by `MessageId` in its own container; a duplicate insert conflicts and is treated as already-processed
 - The marker is written after the consumer's own commit (no ambient transaction) — keep consumer writes idempotent
 
@@ -25,7 +25,7 @@ public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbCon
     public DbSet<InboxMessage> InboxMessages => Set<InboxMessage>();
 
     protected override void OnModelCreating(ModelBuilder modelBuilder)
-        => modelBuilder.ApplyConfiguration(new CosmosInboxMessageEntityConfiguration());
+        => modelBuilder.ApplyCosmosInbox();
 }
 ```
 

docs/articles/packages/vulthil-messaging-inbox-relational.md

@@ -26,7 +26,7 @@ public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
     public DbSet<InboxMessage> InboxMessages => Set<InboxMessage>();
 
     protected override void OnModelCreating(ModelBuilder modelBuilder)
-        => modelBuilder.ApplyConfiguration(new InboxMessageEntityConfiguration());
+        => modelBuilder.ApplyRelationalInbox();
 }
 ```
 

docs/articles/packages/vulthil-sharedkernel-api.md

@@ -48,11 +48,10 @@ app.MapOpenApiEndpoints();
 
 ### Controller-based endpoints
 
-Controllers can return typed results directly for OpenAPI documentation:
+Derive from `BaseController` for the standard `[ApiController]`/route conventions and a `Logger` property resolved for the concrete controller type (no constructor logger argument required). Controllers can return typed results directly for OpenAPI documentation:
 
 ```csharp
-public sealed class UsersController(ILogger<UsersController> logger, ISender sender)
-    : BaseController(logger)
+public sealed class UsersController(ISender sender) : BaseController
 {
     [HttpGet("{id:guid}")]
     public async Task<Results<Ok<UserDto>, ValidationProblem, NotFound, Conflict, ProblemHttpResult>> Get(Guid id)
@@ -66,8 +65,7 @@ public sealed class UsersController(ILogger<UsersController> logger, ISender sen
 Or use `IActionResult` with model-state error translation:
 
 ```csharp
-public sealed class UsersController(ILogger<UsersController> logger, ISender sender)
-    : BaseController(logger)
+public sealed class UsersController(ISender sender) : BaseController
 {
     [HttpGet("{id:guid}")]
     public async Task<IActionResult> Get(Guid id)

docs/articles/packages/vulthil-sharedkernel-infrastructure-cosmos.md

@@ -11,7 +11,7 @@ Use `Vulthil.SharedKernel.Infrastructure.Cosmos` to run the shared infrastructur
 ## Pattern
 
 - Call `UseCosmosDb("connectionName")` on the database infrastructure configurator – it both registers the EF Core context and selects the Cosmos outbox strategy
-- Configure the Cosmos-specific entity model for `OutboxMessage` via `OutboxMessageEntityConfiguration` (applied automatically when `EnableOutboxProcessing` runs)
+- Configure the Cosmos-specific entity model for `OutboxMessage` via the `ApplyCosmosOutbox()` model-builder extension (call it from your `OnModelCreating`)
 - Order between `UseCosmosDb` and `EnableOutboxProcessing` does not matter; the configurator defers the underlying call until the full chain has executed
 
 ## Usage

docs/articles/packages/vulthil-sharedkernel-infrastructure-mysql.md

@@ -1,39 +1,57 @@
 # Vulthil.SharedKernel.Infrastructure.MySql
 
-Use `Vulthil.SharedKernel.Infrastructure.MySql` to select the MySQL-tuned outbox strategy when your `DbContext` runs against MySQL.
+Use `Vulthil.SharedKernel.Infrastructure.MySql` to wire a MySQL-backed `DbContext` together with the MySQL-tuned outbox strategy.
 
 ## When to use
 
 - MySQL is the underlying database for an application's primary `DbContext`
-- Outbox processing should use the MySQL strategy
+- Outbox processing should use the MySQL strategy (row-level locking via `FOR UPDATE SKIP LOCKED`)
 
 ## Pattern
 
-- Call `UseMySql()` on the database infrastructure configurator to swap in the MySQL outbox strategy
-- Register the `DbContext` itself with your preferred MySQL EF Core integration (e.g. `Pomelo.EntityFrameworkCore.MySql`) – `UseMySql` only switches the outbox strategy and does not register the EF Core provider
-- Apply migrations on startup with `MigrateAsync<TDbContext>()` from `Vulthil.SharedKernel.Infrastructure.Relational` (pulled in transitively)
+- Call `UseMySql("ConnectionStringKey")` on the database infrastructure configurator – it registers a pooled EF Core context for the named connection string, selects the MySQL outbox strategy, and (when outbox processing is enabled) wires the commit-time relay trigger
+- Order between `UseMySql` and `EnableOutboxProcessing` does not matter; the configurator defers the underlying registration until the full chain has executed
+- Retrying execution strategies are fully supported – the outbox processor runs its transactional unit inside the context's execution strategy (`Database.CreateExecutionStrategy().ExecuteAsync`)
+
+## Provider
+
+The MySQL EF Core provider is resolved per target framework:
+
+- **.NET 9** – the Aspire client integration [`Aspire.Pomelo.EntityFrameworkCore.MySql`](https://www.nuget.org/packages/Aspire.Pomelo.EntityFrameworkCore.MySql), which resolves the connection string and adds health checks, telemetry, and connection resiliency (parity with the Npgsql and Cosmos integrations)
+- **.NET 10** – the API-compatible [`Microting.EntityFrameworkCore.MySql`](https://www.nuget.org/packages/Microting.EntityFrameworkCore.MySql) fork of Pomelo, registered directly, until the official Pomelo and Aspire packages ship EF Core 10 support
+
+On .NET 10 the MySQL server version is detected from the connection at startup via `ServerVersion.AutoDetect`, so the database must be reachable when the host starts.
 
 ## Usage
 
 ### Registration
 
 ```csharp
-builder.Services.AddDbContext<AppDbContext>(options =>
-    options.UseMySql(
-        builder.Configuration.GetConnectionString("Default"),
-        ServerVersion.AutoDetect(builder.Configuration.GetConnectionString("Default"))));
-
 builder.AddDbContext<AppDbContext>(config => config
-    .UseMySql()
+    .UseMySql("Default")
     .EnableOutboxProcessing(o =>
     {
         o.BatchSize = 25;
         o.MaxRetries = 3;
     }));
 ```
 
+### Configuring the integration
+
+`UseMySql` takes an optional `configure` delegate. Because the Aspire integration only exists on .NET 9, its type differs per target framework — the Aspire `PomeloEntityFrameworkCoreMySqlSettings` on .NET 9, and the EF Core `MySqlDbContextOptionsBuilder` on .NET 10:
+
+```csharp
+// .NET 9 (Aspire) — toggle health checks, tracing, retries, command timeout:
+config.UseMySql("Default", settings => settings.DisableHealthChecks = true);
+
+// .NET 10 (Microting) — configure EF Core/Pomelo options:
+config.UseMySql("Default", mySql => mySql.CommandTimeout(30));
+```
+
 ### Applying migrations on startup
 
+`Vulthil.SharedKernel.Infrastructure.Relational` (pulled in transitively) exposes `MigrateAsync`:
+
 ```csharp
 var app = builder.Build();
 await app.MigrateAsync<AppDbContext>();