@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

package/framework/standards/integration/api/rest-design.md

@@ -1,95 +0,0 @@
-# Integration Standard: REST API Design
-
-## URL Structure
-```
-GET    /api/v1/orders              — list (paginated)
-GET    /api/v1/orders/{id}         — get by ID
-POST   /api/v1/orders              — create
-PUT    /api/v1/orders/{id}         — full update
-PATCH  /api/v1/orders/{id}         — partial update
-DELETE /api/v1/orders/{id}         — delete
-
-GET    /api/v1/users/{id}/orders   — nested resource (ownership)
-POST   /api/v1/orders/{id}/cancel  — verb action (exception to noun rule)
-```
-
-## Request/Response Conventions
-
-### Pagination (always paginate lists)
-```json
-// Request
-GET /api/v1/orders?page=1&pageSize=20&sort=createdAt&order=desc
-
-// Response
-{
-  "data": [...],
-  "pagination": {
-    "page": 1,
-    "pageSize": 20,
-    "total": 150,
-    "totalPages": 8,
-    "hasNext": true,
-    "hasPrevious": false
-  }
-}
-```
-
-### Error Response (RFC 7807 ProblemDetails)
-```json
-{
-  "type": "https://api.myapp.com/errors/validation",
-  "title": "Validation Failed",
-  "status": 422,
-  "detail": "One or more fields failed validation",
-  "instance": "/api/v1/orders",
-  "errors": {
-    "userId": ["UserId is required"],
-    "items": ["At least one item is required"]
-  }
-}
-```
-
-## Status Codes
-| Code | When |
-|------|------|
-| 200 OK | GET, PUT, PATCH success |
-| 201 Created | POST success (include Location header) |
-| 204 No Content | DELETE success |
-| 400 Bad Request | Malformed request body |
-| 401 Unauthorized | Missing/invalid auth token |
-| 403 Forbidden | Valid token, insufficient permissions |
-| 404 Not Found | Resource doesn't exist |
-| 409 Conflict | Duplicate/optimistic lock conflict |
-| 422 Unprocessable | Validation failures |
-| 429 Too Many Requests | Rate limit exceeded (include Retry-After) |
-| 500 Internal Server Error | Unexpected server error |
-
-## Versioning
-- URL versioning: `/api/v1/`, `/api/v2/`
-- Never version via headers (poor discoverability)
-- Maintain N-1 version for 6 months before deprecating
-
-## Minimal API Setup (.NET 10)
-```csharp
-var ordersGroup = app.MapGroup("/api/v1/orders")
-    .RequireAuthorization()
-    .WithTags("Orders")
-    .WithOpenApi();
-
-ordersGroup.MapGet("/", GetOrdersHandler)
-    .WithName("GetOrders")
-    .Produces<PagedResponse<OrderDto>>()
-    .Produces<ProblemDetails>(400);
-
-ordersGroup.MapPost("/", CreateOrderHandler)
-    .WithName("CreateOrder")
-    .Produces<OrderDto>(201)
-    .Produces<ProblemDetails>(422);
-```
-
-## Security Requirements
-- All endpoints require authentication (except /health, /api/docs)
-- Authorization policy per endpoint (not just [Authorize])
-- Rate limiting on write endpoints
-- Input validation via FluentValidation
-- Never expose internal IDs in error messages

package/framework/standards/integration/event-driven/cqrs.md

@@ -1,101 +0,0 @@
-# Integration Standard: CQRS with MediatR
-
-## Overview
-Commands mutate state. Queries read state. Never mix them.
-
-## Setup
-```xml
-<PackageReference Include="MediatR" Version="12.*" />
-<PackageReference Include="MediatR.Extensions.Microsoft.DependencyInjection" Version="11.*" />
-```
-
-```csharp
-// Program.cs
-builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
-```
-
-## Command Pattern
-```csharp
-// Command (mutates state, returns result)
-public record CreateOrderCommand(Guid UserId, List<OrderItem> Items)
-    : IRequest<CreateOrderResult>;
-
-public record CreateOrderResult(Guid OrderId, decimal Total);
-
-// Handler
-public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, CreateOrderResult>
-{
-    public async Task<CreateOrderResult> Handle(CreateOrderCommand cmd, CancellationToken ct)
-    {
-        var order = Order.Create(cmd.UserId, cmd.Items);
-        await _repository.AddAsync(order, ct);
-        await _unitOfWork.SaveChangesAsync(ct);
-
-        // Publish domain event
-        await _publisher.Publish(new OrderCreatedEvent(order.Id), ct);
-
-        return new CreateOrderResult(order.Id, order.Total);
-    }
-}
-```
-
-## Query Pattern
-```csharp
-// Query (reads only, no side effects)
-public record GetOrderQuery(Guid OrderId) : IRequest<OrderDto?>;
-
-// Handler — use read model, not domain entity
-public class GetOrderHandler : IRequestHandler<GetOrderQuery, OrderDto?>
-{
-    public async Task<OrderDto?> Handle(GetOrderQuery query, CancellationToken ct)
-    {
-        return await _context.Orders
-            .Where(o => o.Id == query.OrderId)
-            .Select(o => new OrderDto(o.Id, o.Status, o.Total))
-            .FirstOrDefaultAsync(ct);
-    }
-}
-```
-
-## Pipeline Behaviors (Cross-Cutting)
-```csharp
-// Validation behavior
-public class ValidationBehavior<TRequest, TResponse>
-    : IPipelineBehavior<TRequest, TResponse>
-    where TRequest : IRequest<TResponse>
-{
-    public async Task<TResponse> Handle(TRequest request,
-        RequestHandlerDelegate<TResponse> next, CancellationToken ct)
-    {
-        var failures = _validators
-            .SelectMany(v => v.Validate(request).Errors)
-            .Where(f => f != null)
-            .ToList();
-
-        if (failures.Any())
-            throw new ValidationException(failures);
-
-        return await next();
-    }
-}
-```
-
-## DI Registration Order
-```csharp
-// 1. MediatR (includes handler scanning)
-builder.Services.AddMediatR(cfg =>
-{
-    cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
-    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
-    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(PerformanceBehavior<,>));
-    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
-});
-// 2. FluentValidation
-builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());
-```
-
-## Rules
-- Commands return results, not void (enables error handling)
-- Queries use DTOs, never expose domain entities
-- Never call command handlers from query handlers
-- One handler per Command/Query (no inheritance hierarchies)

package/framework/standards/integration/event-driven/event-sourcing.md

@@ -1,124 +0,0 @@
-# Integration Standard: Event Sourcing
-
-## Overview
-State is derived from a sequence of immutable events. Use only when audit trail or temporal queries are required.
-
-## When to Use
-✅ Financial transactions (audit required by law)
-✅ Order lifecycle (multiple state transitions, replay needed)
-✅ Inventory changes (why did stock go negative?)
-❌ User profiles (too much churn, GDPR deletion complexity)
-❌ Session/cache state (ephemeral, no audit need)
-
-## Event Design
-```csharp
-// Base event
-public abstract record DomainEvent
-{
-    public Guid EventId { get; init; } = Guid.NewGuid();
-    public DateTime OccurredAt { get; init; } = DateTime.UtcNow;
-    public int Version { get; init; }
-    public string EventType => GetType().Name;
-}
-
-// Specific events — past tense, immutable
-public record OrderPlaced(Guid OrderId, Guid UserId, decimal Total, List<OrderItem> Items)
-    : DomainEvent;
-
-public record OrderShipped(Guid OrderId, string TrackingNumber, DateTime ShippedAt)
-    : DomainEvent;
-
-public record OrderCancelled(Guid OrderId, string Reason)
-    : DomainEvent;
-```
-
-## Aggregate with Event Sourcing
-```csharp
-public class Order : AggregateRoot
-{
-    public OrderStatus Status { get; private set; }
-    public decimal Total { get; private set; }
-
-    // Reconstruct from events
-    public static Order Replay(IEnumerable<DomainEvent> events)
-    {
-        var order = new Order();
-        foreach (var e in events) order.Apply(e);
-        return order;
-    }
-
-    // Command → validate → raise event
-    public void Ship(string trackingNumber)
-    {
-        if (Status != OrderStatus.Confirmed)
-            throw new InvalidOperationException($"Cannot ship order in {Status} status");
-
-        RaiseEvent(new OrderShipped(Id, trackingNumber, DateTime.UtcNow));
-    }
-
-    // State transition from event (idempotent)
-    protected override void Apply(DomainEvent @event)
-    {
-        switch (@event)
-        {
-            case OrderPlaced e:
-                Id = e.OrderId;
-                Total = e.Total;
-                Status = OrderStatus.Pending;
-                break;
-
-            case OrderShipped e:
-                Status = OrderStatus.Shipped;
-                break;
-
-            case OrderCancelled:
-                Status = OrderStatus.Cancelled;
-                break;
-        }
-    }
-}
-```
-
-## Event Store (Azure Cosmos DB pattern)
-```csharp
-public class CosmosEventStore : IEventStore
-{
-    public async Task AppendAsync(Guid streamId, IEnumerable<DomainEvent> events, int expectedVersion)
-    {
-        foreach (var (evt, i) in events.Select((e, i) => (e, i)))
-        {
-            var document = new EventDocument
-            {
-                Id = $"{streamId}:{expectedVersion + i + 1}",
-                StreamId = streamId.ToString(),
-                Version = expectedVersion + i + 1,
-                EventType = evt.EventType,
-                Data = JsonSerializer.Serialize(evt, evt.GetType()),
-                OccurredAt = evt.OccurredAt
-            };
-            await _container.CreateItemAsync(document, new PartitionKey(streamId.ToString()));
-        }
-    }
-}
-```
-
-## Projections (Read Models)
-```csharp
-// Project events to read-optimized views
-public class OrderSummaryProjection
-{
-    public void Handle(OrderPlaced e, AppDbContext ctx)
-        => ctx.OrderSummaries.Add(new OrderSummary { Id = e.OrderId, Total = e.Total, Status = "Pending" });
-
-    public void Handle(OrderShipped e, AppDbContext ctx)
-        => ctx.OrderSummaries.Where(s => s.Id == e.OrderId).ExecuteUpdate(s => s.SetProperty(p => p.Status, "Shipped"));
-}
-```
-
-## Trade-offs
-| Pro | Con |
-|-----|-----|
-| Complete audit trail | Schema evolution complexity |
-| Temporal queries (state at time T) | Higher storage cost |
-| Event replay for debugging | Eventual consistency for read models |
-| Natural integration events | GDPR deletion requires event masking |

package/framework/standards/integration/event-driven/service-bus.md

@@ -1,95 +0,0 @@
-# Integration Standard: Azure Service Bus
-
-## Patterns
-
-### Queue vs Topic
-- **Queue**: Point-to-point, one consumer per message. Use for jobs, commands.
-- **Topic + Subscription**: Fan-out, multiple consumers. Use for domain events.
-
-### Sender Pattern
-```csharp
-public class ServiceBusSender<T>
-{
-    private readonly ServiceBusSender _sender;
-
-    public async Task SendAsync(T message, CancellationToken ct = default)
-    {
-        var json = JsonSerializer.Serialize(message);
-        var serviceBusMessage = new ServiceBusMessage(json)
-        {
-            ContentType = "application/json",
-            MessageId = Guid.NewGuid().ToString(),
-            Subject = typeof(T).Name // For filtering
-        };
-        await _sender.SendMessageAsync(serviceBusMessage, ct);
-    }
-}
-```
-
-### Receiver Pattern (with IHostedService)
-```csharp
-public class OrderProcessor : IHostedService
-{
-    private ServiceBusProcessor _processor;
-
-    public async Task StartAsync(CancellationToken ct)
-    {
-        _processor.ProcessMessageAsync += HandleMessageAsync;
-        _processor.ProcessErrorAsync += HandleErrorAsync;
-        await _processor.StartProcessingAsync(ct);
-    }
-
-    private async Task HandleMessageAsync(ProcessMessageEventArgs args)
-    {
-        var order = JsonSerializer.Deserialize<OrderCreatedEvent>(args.Message.Body);
-        await _orderService.ProcessAsync(order!);
-        await args.CompleteMessageAsync(args.Message);
-    }
-
-    private Task HandleErrorAsync(ProcessErrorEventArgs args)
-    {
-        _logger.LogError(args.Exception, "Service Bus error on {EntityPath}", args.EntityPath);
-        return Task.CompletedTask; // Abandon → retry → dead-letter
-    }
-}
-```
-
-### Dead-Letter Processing
-```csharp
-// Check dead-letter queue periodically
-var client = new ServiceBusClient(connectionString);
-var receiver = client.CreateReceiver(queueName, new ServiceBusReceiverOptions
-{
-    SubQueue = SubQueue.DeadLetter
-});
-
-await foreach (var msg in receiver.ReceiveMessagesAsync())
-{
-    _logger.LogError("Dead-lettered: {Reason} | Body: {Body}",
-        msg.DeadLetterReason, msg.Body.ToString());
-    await receiver.CompleteMessageAsync(msg);
-}
-```
-
-## Retry Policy
-- MaxDeliveryCount: 5 (queue setting)
-- Lock duration: 5 minutes (for long-processing messages)
-- Dead-letter after MaxDeliveryCount exceeded
-
-## Required Settings
-```json
-{
-  "ServiceBus": {
-    "ConnectionString": "from-key-vault",
-    "QueueName": "feature-name-queue",
-    "MaxConcurrentCalls": 4,
-    "PrefetchCount": 10
-  }
-}
-```
-
-## Anti-Patterns
-- Never use connection string in code — always Key Vault
-- Never process in `HandleErrorAsync` — only log
-- Never use topics for commands (use queues)
-- Never use synchronous sends in Blazor components

package/framework/standards/observability/logging.md

@@ -1,131 +0,0 @@
-# Observability Standard: Logging
-
-## Overview
-Structured logging with Serilog, enrichers, sinks, and log level configuration.
-
-## Serilog Setup
-
-### Package Installation
-```xml
-<PackageReference Include="Serilog.AspNetCore" Version="8.*" />
-<PackageReference Include="Serilog.Enrichers.Environment" Version="3.*" />
-<PackageReference Include="Serilog.Enrichers.Process" Version="3.*" />
-<PackageReference Include="Serilog.Enrichers.Thread" Version="4.*" />
-<PackageReference Include="Serilog.Sinks.ApplicationInsights" Version="4.*" />
-```
-
-### Program.cs Configuration
-```csharp
-Log.Logger = new LoggerConfiguration()
-    .ReadFrom.Configuration(builder.Configuration)
-    .Enrich.FromLogContext()
-    .Enrich.WithEnvironmentName()
-    .Enrich.WithMachineName()
-    .Enrich.WithProcessId()
-    .Enrich.WithThreadId()
-    .WriteTo.Console(outputTemplate:
-        "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}")
-    .WriteTo.ApplicationInsights(
-        builder.Configuration["ApplicationInsights:ConnectionString"],
-        TelemetryConverter.Traces)
-    .CreateLogger();
-
-builder.Host.UseSerilog();
-```
-
-### appsettings.json Level Configuration
-```json
-{
-  "Serilog": {
-    "MinimumLevel": {
-      "Default": "Information",
-      "Override": {
-        "Microsoft": "Warning",
-        "Microsoft.Hosting.Lifetime": "Information",
-        "System": "Warning",
-        "Microsoft.EntityFrameworkCore": "Warning"
-      }
-    }
-  }
-}
-```
-
-## Structured Logging Patterns
-
-### Correct: Structured Properties
-```csharp
-// ✅ Use structured logging — properties are searchable in App Insights
-logger.LogInformation("User {UserId} created order {OrderId} for {Amount:C}",
-    userId, orderId, amount);
-
-// ✅ Log exceptions with context
-logger.LogError(ex, "Failed to process payment for order {OrderId} (attempt {Attempt}/{MaxAttempts})",
-    orderId, attempt, maxAttempts);
-```
-
-### Wrong: String Interpolation
-```csharp
-// ❌ Never use string interpolation — loses structured properties
-logger.LogInformation($"User {userId} created order {orderId}");
-
-// ❌ Never concatenate
-logger.LogError("Failed for order " + orderId);
-```
-
-## Log Scopes
-```csharp
-// Add correlation context for a request scope
-using (logger.BeginScope(new Dictionary<string, object>
-{
-    ["CorrelationId"] = correlationId,
-    ["UserId"] = userId,
-    ["Feature"] = "checkout"
-}))
-{
-    // All logs within this scope include the properties above
-    await ProcessCheckoutAsync(cart);
-}
-```
-
-## Log Categories — What to Log
-
-| Level | When |
-|-------|------|
-| `Trace` | Never in production (dev only) |
-| `Debug` | Detailed flow, timing — disabled in prod |
-| `Information` | Business events: order created, user signed in, job started |
-| `Warning` | Degraded state: retry, rate limit, cache miss cascade |
-| `Error` | Handled exceptions: payment failed, validation error |
-| `Critical` | System failures: database unavailable, startup failure |
-
-## Sensitive Data — NEVER Log
-- Passwords or hashed passwords
-- Credit card numbers or CVV
-- Social security numbers
-- JWT tokens or API keys
-- Full connection strings
-- PII beyond user ID (no email, phone, address)
-
-## Performance Logging Pattern
-```csharp
-public class PerformanceLoggingBehavior<TRequest, TResponse>
-    : IPipelineBehavior<TRequest, TResponse>
-{
-    private readonly ILogger<PerformanceLoggingBehavior<TRequest, TResponse>> _logger;
-
-    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken ct)
-    {
-        var sw = Stopwatch.StartNew();
-        var response = await next();
-        sw.Stop();
-
-        if (sw.ElapsedMilliseconds > 500)
-        {
-            _logger.LogWarning("Slow request {RequestName} took {ElapsedMs}ms",
-                typeof(TRequest).Name, sw.ElapsedMilliseconds);
-        }
-
-        return response;
-    }
-}
-```

package/framework/standards/observability/metrics.md

@@ -1,121 +0,0 @@
-# Observability Standard: Metrics
-
-## Overview
-Custom metrics with .NET Meters API and Azure Monitor integration.
-
-## Metrics Setup
-
-### Packages
-```xml
-<PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.*" />
-<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="0.*" />
-```
-
-### Meter Definition (per feature/service)
-```csharp
-// Define meters as static singletons
-public static class AppMetrics
-{
-    private static readonly Meter Meter = new("MyApp.Business", "1.0.0");
-
-    // Counters (monotonically increasing)
-    public static readonly Counter<long> OrdersCreated =
-        Meter.CreateCounter<long>("orders.created", "orders", "Total orders created");
-
-    public static readonly Counter<long> PaymentsFailed =
-        Meter.CreateCounter<long>("payments.failed", "failures", "Total payment failures");
-
-    // Histograms (distributions)
-    public static readonly Histogram<double> OrderProcessingTime =
-        Meter.CreateHistogram<double>("orders.processing_time", "ms", "Order processing duration");
-
-    // Gauges (current value)
-    public static readonly ObservableGauge<int> ActiveConnections =
-        Meter.CreateObservableGauge<int>("connections.active", GetActiveConnections, "connections");
-
-    private static int GetActiveConnections() => ConnectionPool.ActiveCount;
-}
-```
-
-### Recording Metrics
-```csharp
-// Counter increment
-AppMetrics.OrdersCreated.Add(1, new TagList
-{
-    { "status", "success" },
-    { "payment_method", order.PaymentMethod }
-});
-
-// Histogram measurement
-var sw = Stopwatch.StartNew();
-await ProcessOrderAsync(order);
-AppMetrics.OrderProcessingTime.Record(sw.ElapsedMilliseconds, new TagList
-{
-    { "order_type", order.Type },
-    { "region", order.Region }
-});
-```
-
-### Register with OpenTelemetry
-```csharp
-builder.Services.AddOpenTelemetry()
-    .WithMetrics(metrics =>
-    {
-        metrics
-            .AddAspNetCoreInstrumentation()
-            .AddHttpClientInstrumentation()
-            .AddRuntimeInstrumentation()
-            .AddMeter("MyApp.Business")
-            .AddAzureMonitorMetricExporter(opts =>
-            {
-                opts.ConnectionString = config["ApplicationInsights:ConnectionString"];
-            });
-    });
-```
-
-## Required Business Metrics
-
-| Metric | Type | Tags | Why |
-|--------|------|------|-----|
-| `requests.total` | Counter | route, method, status | Request volume |
-| `requests.duration` | Histogram | route, status | Latency distribution |
-| `errors.total` | Counter | type, severity | Error rate |
-| `{domain}.operations` | Counter | operation, result | Business KPIs |
-| `db.query_duration` | Histogram | table, operation | DB performance |
-| `queue.depth` | Gauge | queue_name | Backlog monitoring |
-| `cache.hit_rate` | Gauge | cache_name | Cache effectiveness |
-
-## KQL Metric Queries
-
-### Request Volume by Endpoint
-```kql
-customMetrics
-| where name == "requests.total" and timestamp > ago(1h)
-| summarize total = sum(value) by bin(timestamp, 5m), tostring(customDimensions["route"])
-| render timechart
-```
-
-### P50/P95/P99 Latency
-```kql
-customMetrics
-| where name == "requests.duration" and timestamp > ago(1h)
-| summarize
-    p50 = percentile(value, 50),
-    p95 = percentile(value, 95),
-    p99 = percentile(value, 99)
-  by bin(timestamp, 5m)
-| render timechart
-```
-
-## Naming Conventions
-
-| Pattern | Example | Description |
-|---------|---------|-------------|
-| `{domain}.{noun}.{verb}` | `orders.items.created` | Domain event count |
-| `{resource}.{metric}` | `db.query_duration` | Resource measurement |
-| `{service}.{noun}.active` | `connections.sockets.active` | Current state |
-
-Rules:
-- Lowercase with dots as separators
-- Use consistent units: `ms` for duration, `bytes` for size, `count` for dimensionless
-- Include relevant tags (avoid high-cardinality tags like userId)