@polymorphism-tech/morph-spec 8.46.0 → 8.47.0

package/framework/standards/backend/dotnet/fluent-validation-vsa.md

@@ -1,11 +1,11 @@
 # FluentValidation in VSA Pipelines
 
 > **Scope:** dotnet-vsa
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` ao editar `**/*.cs`/`**/*.csproj`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** fluent-validation, validation, decorator, pipeline, vsa
 > **Load When:** dotnet VSA projects
 
-**Verified against:** .NET 10 + FluentValidation 11 (`AbstractValidator`/`RuleFor` API). Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + FluentValidation 12.1.1. The validator block and the decorator (its three blocks assembled into one class) compile with `TreatWarningsAsErrors` over the `Result`/`ValidationError` of `result-pattern.md`, and the validator was run with `FakeTimeProvider` across a year change to show the year is read per validation. Last-verified: 2026-10-03.
 
 ---
 
@@ -21,11 +21,10 @@ One validator per request DTO. Lives in the same feature folder as the handler:
 
 ```csharp
 // Features/BookFeature/CreateBook/CreateBookValidator.cs
-public class CreateBookValidator : AbstractValidator<CreateBookRequest>
+using FluentValidation;
+
+public sealed class CreateBookValidator : AbstractValidator<CreateBookRequest>
 {
-    // TimeProvider injected, never DateTime.UtcNow read directly — see
-    // backend-dotnet-testing (Rule 1): a validator that reads the real clock
-    // cannot be tested deterministically with FakeTimeProvider.
     public CreateBookValidator(TimeProvider timeProvider)
     {
         RuleFor(c => c.Title)
@@ -44,12 +43,16 @@ public class CreateBookValidator : AbstractValidator<CreateBookRequest>
 
         RuleFor(c => c.PublishedYear)
             .GreaterThan(1000).WithMessage("Published year must be a valid year")
-            .LessThanOrEqualTo(timeProvider.GetUtcNow().Year)
+            .LessThanOrEqualTo(_ => timeProvider.GetUtcNow().Year)
             .WithMessage("Published year cannot be in the future");
     }
 }
 ```
 
+- `sealed`, like every class in the slice.
+- The clock is `TimeProvider` (never `DateTime.UtcNow`), so `FakeTimeProvider` makes the rule testable (`backend-dotnet-testing`, Rule 1).
+- The year is read **inside the rule** (`_ => timeProvider.GetUtcNow().Year`), on every validation. `AddValidatorsFromAssembly` registers validators as scoped by default, but a validator registered as singleton (or cached) that captured `GetUtcNow().Year` in the constructor would keep rejecting next year's books from 1 January on.
+
 ---
 
 ## Auto-Discovery
@@ -69,6 +72,9 @@ builder.Services.AddHandlersFromAssembly(typeof(Program).Assembly);
 The decorator wraps every `IHandler<TRequest, TResponse>` via Scrutor. It collects all `IValidator<TRequest>` from DI, runs them in parallel, and short-circuits on failure:
 
 ```csharp
+using FluentValidation;
+using FluentValidation.Results;
+
 public sealed class ValidationDecorator<TRequest, TResponse>(
     IEnumerable<IValidator<TRequest>> validators,
     IHandler<TRequest, TResponse> innerHandler) : IHandler<TRequest, TResponse>
@@ -194,7 +200,7 @@ Features/
 
 | Do NOT | Do Instead |
 |--------|------------|
-| Validate inside the handler | Use `AbstractValidator<T>` + decorator |
+| Validate request shape inside the handler | Use `AbstractValidator<T>` + decorator (state/existence checks do belong in the handler -- `backend/api/validation.md`) |
 | Throw `ValidationException` | Return `Result.Failure(ValidationError)` |
 | Register validators after handlers | Register validators first: `AddValidatorsFromAssembly()` before `AddHandlersFromAssembly()` |
 | Put validation logic in endpoints | Endpoints only do `Match()` — validation is automatic |

package/framework/standards/backend/dotnet/result-pattern.md

@@ -1,11 +1,11 @@
 # Result Pattern — Railway-Oriented Programming
 
 > **Scope:** dotnet-vsa
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` ao editar `**/*.cs`/`**/*.csproj`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** result, error-handling, railway, match, monadic
 > **Load When:** dotnet VSA projects
 
-**Verified against:** .NET 10 (pure C# pattern — no external package). Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + the shared framework `Microsoft.AspNetCore.App` 10 — the HTTP mapping uses `Results`/`IResult`/`StatusCodes`; the `Error`, `ValidationError`, `ResultExtensions`, `ErrorHttpMapping`, endpoint usage and `BookErrors` blocks compile with `TreatWarningsAsErrors` (the Anatomy blocks carry `{ ... }` placeholders and were compiled through a concrete stand-in). Last-verified: 2026-10-03.
 
 ---
 
@@ -118,6 +118,7 @@ public enum ErrorType
 | `NotFound` | 404 | Entity lookup returned null |
 | `Unauthorized` | 401 | Missing or invalid auth token |
 | `Forbidden` | 403 | Authenticated but lacks permission |
+| `Custom` | 400 | Domain-specific; a feature that needs another status maps it in its own endpoint |
 
 ---
 
@@ -145,7 +146,7 @@ public sealed record ValidationError : Error
 
 ## Match() Pattern
 
-Endpoints use `Match()` to convert `Result<T>` into HTTP responses — never access `.Value` directly:
+Endpoints use `Match()` to convert `Result<T>` into HTTP responses — never access `.Value` directly (the success lambda receives the value; `Match` itself is the only reader of `.Value`):
 
 ```csharp
 public static class ResultExtensions
@@ -170,15 +171,48 @@ public static class ResultExtensions
 }
 ```
 
+The failure side maps by `ErrorType`, following the table above — never `Results.BadRequest` for every error, which turns a missing entity into a 400 and a conflict into a 400:
+
+```csharp
+public static class ErrorHttpMapping
+{
+    public static int StatusCodeFor(ErrorType type) => type switch
+    {
+        ErrorType.Validation => StatusCodes.Status400BadRequest,
+        ErrorType.NotFound => StatusCodes.Status404NotFound,
+        ErrorType.Conflict => StatusCodes.Status409Conflict,
+        ErrorType.Unauthorized => StatusCodes.Status401Unauthorized,
+        ErrorType.Forbidden => StatusCodes.Status403Forbidden,
+        ErrorType.Unexpected => StatusCodes.Status500InternalServerError,
+        _ => StatusCodes.Status400BadRequest
+    };
+
+    public static IResult ToHttpResult(this Error error)
+    {
+        Dictionary<string, object?>? extensions = error is ValidationError validation
+            ? new() { ["errors"] = validation.Errors.Select(e => new { e.Code, e.Description }).ToArray() }
+            : null;
+
+        return Results.Problem(
+            title: error.Code,
+            detail: error.Description,
+            statusCode: StatusCodeFor(error.Type),
+            extensions: extensions);
+    }
+}
+```
+
 Usage in an endpoint:
 
 ```csharp
-var result = await handler.HandleAsync(command, cancellationToken);
+var result = await handler.HandleAsync(query, cancellationToken);
 return result.Match(
-    onSuccess: () => Results.Ok(result.Value),
-    onFailure: error => Results.BadRequest(error));
+    onSuccess: book => Results.Ok(book),
+    onFailure: error => error.ToHttpResult());
 ```
 
+For a handler that returns `Result` (no value), the success lambda takes no argument: `result.Match(onSuccess: () => Results.NoContent(), onFailure: error => error.ToHttpResult())`.
+
 ---
 
 ## Defining Feature Errors

package/framework/standards/backend/dotnet/scalar-ui.md

@@ -1,11 +1,11 @@
 # Scalar.AspNetCore — API Documentation UI
 
 > **Scope:** dotnet-vsa
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` ao editar `**/*.cs`/`**/*.csproj`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** scalar, openapi, swagger, api-docs, documentation
 > **Load When:** dotnet VSA projects
 
-**Verified against:** .NET 10 + Scalar.AspNetCore 2.x + Microsoft.AspNetCore.OpenApi 10. Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Scalar.AspNetCore 2.x + Microsoft.AspNetCore.OpenApi 10. The `ApiTags` and tagged-endpoint blocks compile with `TreatWarningsAsErrors` over the `Result`/`ErrorHttpMapping` of `result-pattern.md` (ApiTags placed in `ProjectName.Constants`); the startup and metadata snippets (`async (...) => { ... }`) are fragments, checked against the docs only. Last-verified: 2026-10-03.
 
 ---
 
@@ -91,6 +91,10 @@ public static class ApiTags
 Apply tags in endpoints:
 
 ```csharp
+using ProjectName.Abstractions;
+using ProjectName.Constants;
+using ProjectName.Extensions;
+
 internal sealed class CreateBookEndpoint : IApiEndpoint
 {
     public void MapEndpoint(IEndpointRouteBuilder app)
@@ -102,16 +106,18 @@ internal sealed class CreateBookEndpoint : IApiEndpoint
         {
             var result = await handler.HandleAsync(command, cancellationToken);
             return result.Match(
-                onSuccess: () => Results.Ok(result.Value),
-                onFailure: error => Results.BadRequest(error));
+                onSuccess: response => Results.Ok(response),
+                onFailure: error => error.ToHttpResult());
         })
         .WithTags(ApiTags.Books)
         .Produces<CreateBookResponse>(StatusCodes.Status200OK)
-        .Produces(StatusCodes.Status400BadRequest);
+        .ProducesProblem(StatusCodes.Status400BadRequest);
     }
 }
 ```
 
+The failure side is `error.ToHttpResult()` (`Extensions/ErrorHttpMapping.cs`, see `backend/dotnet/result-pattern.md`): the `ErrorType` picks the status and the body is ProblemDetails, so document every failure status the slice can return with `.ProducesProblem(status)` — a 404/409 the endpoint can emit but does not declare is a lie in the Scalar docs.
+
 ---
 
 ## Endpoint Metadata
@@ -124,12 +130,12 @@ app.MapGet("books/{id:guid}", async (...) => { ... })
     .WithName("GetBookById")
     .WithSummary("Get a book by its unique identifier")
     .Produces<GetBookResponse>(StatusCodes.Status200OK)
-    .Produces(StatusCodes.Status404NotFound);
+    .ProducesProblem(StatusCodes.Status404NotFound);
 
 app.MapDelete("books/{id:guid}", async (...) => { ... })
     .WithTags(ApiTags.Books)
     .Produces(StatusCodes.Status204NoContent)
-    .Produces(StatusCodes.Status404NotFound);
+    .ProducesProblem(StatusCodes.Status404NotFound);
 ```
 
 ### Common Metadata Methods

package/framework/standards/backend/dotnet/scrutor.md

@@ -1,7 +1,7 @@
 # Scrutor 7.0.0 — Auto-Discovery & Decorator Registration
 
 > **Scope:** dotnet-vsa
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` ao editar `**/*.cs`/`**/*.csproj`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** scrutor, di, decorators, auto-discovery, assembly-scanning
 > **Load When:** dotnet VSA projects
 

package/framework/standards/backend/dotnet/testing.md

@@ -1,7 +1,7 @@
 # .NET Integration Testing — VSA
 
 > **Scope:** dotnet-vsa
-> **Layer:** 0 (always load)
+> **Layer:** 1 (lista das personas `dotnet-senior`, `ef-modeler`, `maf-expert` e `infra-engineer`; nenhuma rule o resume — fora delas, sob demanda via `morph-spec standards --find`)
 > **Keywords:** testing, xunit, integration test, TimeProvider, FakeTimeProvider, WebApplicationFactory, ProblemDetails, error body assertion
 > **Load When:** writing or reviewing tests for a dotnet VSA project
 

package/framework/standards/backend/dotnet/vsa-handler-patterns.md

@@ -1,11 +1,11 @@
 # VSA Handler Patterns — Complete Feature Slice Guide
 
 > **Scope:** dotnet-vsa
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` ao editar `**/*.cs`/`**/*.csproj`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** vsa, handler, feature-slice, vertical-slice, minimal-api, endpoint
 > **Load When:** dotnet VSA projects
 
-**Verified against:** .NET 10 (minimal APIs, primary constructors, `Guid.CreateVersion7()`). Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview; minimal APIs, primary constructors, `Guid.CreateVersion7()`). The "Complete Endpoint Example" block compiles with `TreatWarningsAsErrors` over the `Result`/`ErrorHttpMapping` of `result-pattern.md` (in `ProjectName.Abstractions`/`ProjectName.Extensions`, reached only through the block's own `using`s); the other blocks are documentary. Last-verified: 2026-10-03.
 
 ---
 
@@ -137,12 +137,12 @@ internal sealed class CreateBookEndpoint : IApiEndpoint
         {
             var result = await handler.HandleAsync(command, cancellationToken);
             return result.Match(
-                onSuccess: () => Results.Ok(result.Value),
-                onFailure: error => Results.BadRequest(error));
+                onSuccess: response => Results.Ok(response),
+                onFailure: error => error.ToHttpResult());
         })
         .WithTags(ApiTags.Books)
         .Produces<CreateBookResponse>(StatusCodes.Status200OK)
-        .Produces(StatusCodes.Status400BadRequest);
+        .ProducesProblem(StatusCodes.Status400BadRequest);
     }
 }
 ```
@@ -152,9 +152,9 @@ internal sealed class CreateBookEndpoint : IApiEndpoint
 - **`internal sealed`** — endpoints are not public API
 - **`IApiEndpoint`** — single interface for auto-discovery
 - **Handler injected via DI** — resolved as `IHandler<TReq, TRes>` parameter
-- **`Match()` for responses** — never access `.Value` directly
+- **`Match()` for responses** — the success lambda receives the value (never read `.Value` directly); the failure lambda is `error.ToHttpResult()` from `Extensions/ErrorHttpMapping.cs` (`backend/dotnet/result-pattern.md`), which maps `ErrorType` to the status — never `Results.BadRequest` for every error
 - **`.WithTags()`** — always tag for Scalar API docs
-- **`.Produces<T>()`** — always document response types
+- **`.Produces<T>()` + `.ProducesProblem(status)`** — document the success type and every failure status the slice can return
 
 ---