Feature/messaging hardening

.github/copilot-instructions.md

@@ -1,10 +1,25 @@
 # Copilot Instructions
 
+## Git Guidelines
+- Do not commit without an explicit permission. Allow the developers a change to review the code to provide feedback before commiting.
+- Do not create commit descriptions. Only suggest the one line commit message that describes the change.
+
 ## Project Guidelines
 - Use a lazy `Target` pattern from `CreateInstance<T>` when inheriting from `BaseUnitTestCase` (or `BaseUnitTestCase<T>` when accessibility allows) for test classes in this repository.
 - When modifying a public member, make sure to update the XML Documentation and the corresponding docs in the docs folder and the README file if applicable.
 - When modifying a public member, make sure to check the Public.API files for the affected assembly and update them if necessary.
 - Do not ignore CS1591 warnings; analyze and add missing XML comments instead.
+- Do not add comments inside methods; for complex logic, consider extracting it into a separate method with a descriptive name instead of adding comments.
+
+## Testing Guidelines
+- Prefer using the Vulthil.xUnit testing framework for tests.
+- When writing tests, follow the Arrange-Act-Assert pattern for better readability and maintainability.
+- Prefer using the BaseUnitTestCase or BaseUnitTestCase<T> classes for test cases to leverage common setup and utilities.
+- Prefer using the `CancellationToken` property on the base test classes, instead of getting the `TestContext.Current.CancellationToken` directly.
+- Prefer using the AutoMocker instance for dependency injection in tests to simplify test setup and improve readability.
+- Use the methods on the BaseUnitTestCase class for modifying the AutoMocker instance, such as `Use<T>(T instance)` or `Use<T>()` for registering dependencies, and `GetMock<T>()` for retrieving mocks from the AutoMocker.
+- Override the CreateInstance or CreateInstance<T> methods and use the Target property to lazily create the instance under test.
+- Do not add comments inside test methods except Arrange, Act and Assert; rename the test method to be descriptive of the behavior being tested instead of adding comments.
 
 ## Documentation Guidelines
 - When generating package README files, keep them short and concise, and use the docs folder for more elaborate usage patterns.

documentation-guidelines.instructions.md → .github/instructions/documentation-guidelines.instructions.md

@@ -7,7 +7,10 @@ apply-to: "src/**/*.*"
 When assisting with this C# solution, you MUST adhere to the following documentation standards for all code modifications, additions, and refactors. Failure to maintain these standards will result in build warnings, CI/CD failures, or degraded documentation.
 
 ## 1. XML Documentation for Public Members
-All `public` types and members (classes, structs, interfaces, records, enums, methods, properties, events, and fields) REQUIRE standard C# XML documentation comments (`///`). 
+Add standard C# XML documentation comments (`///`) only where the compiler would otherwise emit **CS1591** ("Missing XML comment for publicly visible type or member").
+In practice this covers `public` types and members (classes, structs, interfaces, records, enums, methods, properties, events, and fields) in assemblies that generate a documentation file.
+Do not add `///` comments to members the compiler does not warn about (e.g., `internal`, `private`, or `protected` members, or members already covered by an enclosing `<inheritdoc />`),
+as this adds noise without satisfying any analyzer requirement. 
 
 *   **Required Tags:** Always include a `<summary>`. 
 *   **Contextual Tags:** Include `<param>`, `<returns>`, `<value>`, `<remarks>`, and `<exception>` tags wherever applicable.
@@ -33,7 +36,7 @@ The conceptual documentation is housed in the `docs` folder and is built using D
 
 ## Agent Verification Checklist
 Before completing your task, verify the following:
-- [ ] Did I add `///` comments to all newly created or modified `public` members?
+- [ ] Did I add `///` comments to every newly created or modified member that would otherwise trigger CS1591 (and avoid adding them where the compiler does not warn)?
 - [ ] Did I add the exact API signature to `PublicAPI.Unshipped.txt`?
 - [ ] Did I add/update usage examples in the `docs` folder?
 - [ ] Are my conceptual doc changes compatible with `docs/docfx.json` and the Table of Contents?

Directory.Packages.props

@@ -6,7 +6,7 @@
   <PropertyGroup>
     <FrameworkVersion>10.0.8</FrameworkVersion>
     <FrameworkVersion Condition="'$(TargetFramework)' == 'net9.0'">9.0.16</FrameworkVersion>
-    <AspireVersion>13.3.5</AspireVersion>
+    <AspireVersion>13.4.2</AspireVersion>
   </PropertyGroup>
   <ItemGroup>
     <PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="$(AspireVersion)" />
@@ -53,7 +53,6 @@
     <PackageVersion Include="Respawn" Version="7.0.0" />
     <PackageVersion Include="Scalar.Aspire" Version="0.9.37" />
     <PackageVersion Include="Scalar.AspNetCore" Version="2.11.6" />
-    <PackageVersion Include="Scrutor" Version="7.0.0" />
     <PackageVersion Include="Shouldly" Version="4.3.0" />
     <PackageVersion Include="SonarAnalyzer.CSharp" Version="10.27.0.140913" />
     <PackageVersion Include="Testcontainers" Version="4.12.0" />

Vulthil.SharedKernel.slnx

@@ -7,8 +7,8 @@
     <File Path=".github/dependabot.yml" />
   </Folder>
   <Folder Name="/.github/instructions/">
+    <File Path=".github/instructions/documentation-guidelines.instructions.md" />
     <File Path=".github/instructions/style-guidelines.instructions.md" />
-    <File Path="documentation-guidelines.instructions.md" />
   </Folder>
   <Folder Name="/.github/workflows/">
     <File Path=".github/workflows/ci.yml" />
@@ -44,6 +44,8 @@
     <File Path=".editorconfig" />
     <File Path=".gitattributes" />
     <File Path=".gitignore" />
+    <File Path="CLAUDE.md" />
+    <File Path="cliff.toml" />
     <File Path="Directory.Build.props" />
     <File Path="Directory.Packages.props" />
     <File Path="global.json" />
@@ -83,6 +85,7 @@
   <Folder Name="/tests/">
     <Project Path="tests/Vulthil.Messaging.Abstractions.Tests/Vulthil.Messaging.Abstractions.Tests.csproj" />
     <Project Path="tests/Vulthil.Messaging.RabbitMq.Tests/Vulthil.Messaging.RabbitMq.Tests.csproj" />
+    <Project Path="tests/Vulthil.Messaging.TestHarness.Tests/Vulthil.Messaging.TestHarness.Tests.csproj" />
     <Project Path="tests/Vulthil.Messaging.Tests/Vulthil.Messaging.Tests.csproj" />
     <Project Path="tests/Vulthil.Results.Tests/Vulthil.Results.Tests.csproj" />
     <Project Path="tests/Vulthil.SharedKernel.Application.Tests/Vulthil.SharedKernel.Application.Tests.csproj" />
@@ -100,5 +103,6 @@
   </Folder>
   <Folder Name="/tests/Test Items/">
     <File Path="tests/Directory.Build.props" />
+    <File Path="tests/Vulthil.TestRunner.props" />
   </Folder>
 </Solution>

docs/articles/cqrs-pipeline.md

@@ -121,3 +121,28 @@ app.MapPost("/users", async (CreateUserCommand command, ISender sender) =>
     return result.ToIResult();
 });
 ```
+
+### Direct handler injection
+
+You can also inject the handler interface directly. The resolved instance is the same pipeline-wrapped handler that `ISender` would dispatch to, so behaviors (validation, logging, transactions, custom ones) apply uniformly either way.
+
+```csharp
+app.MapPost("/users", async (
+    CreateUserCommand command,
+    ICommandHandler<CreateUserCommand, Result<Guid>> handler) =>
+{
+    var result = await handler.HandleAsync(command);
+    return result.ToIResult();
+});
+```
+
+The interfaces you can inject are `IHandler<TRequest, TResponse>`, `ICommandHandler<TCommand, TResponse>`, `ICommandHandler<TCommand>` (for `Result`-returning commands) and `IQueryHandler<TQuery, TResponse>`. The concrete handler implementation is *not* registered as a DI service — there is no way to bypass the pipeline by injecting the concrete type.
+
+## Behaviors across assemblies
+
+Pipeline behaviors are composed at handler-resolution time, not at registration time, so the order of registration is irrelevant. Different assemblies may register handlers and behaviors independently — all behaviors registered before `BuildServiceProvider` apply to all handlers resolved afterwards.
+
+```csharp
+// In an Infrastructure assembly:
+services.AddOpenPipelineHandler(typeof(MyCustomBehavior<,>));
+```