@polymorphism-tech/morph-spec 4.3.4 → 4.3.6

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

@@ -0,0 +1,101 @@
+# 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/.morph/standards/integration/event-driven/event-sourcing.md

@@ -0,0 +1,124 @@
+# 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/.morph/standards/integration/event-driven/service-bus.md

@@ -0,0 +1,95 @@
+# 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/.morph/standards/observability/logging.md

@@ -0,0 +1,131 @@
+# 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/.morph/standards/observability/metrics.md

@@ -0,0 +1,121 @@
+# 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)

package/.morph/standards/observability/monitoring.md

@@ -0,0 +1,114 @@
+# Observability Standard: Monitoring
+
+## Overview
+Application Insights configuration and KQL query patterns for production monitoring.
+
+## Application Insights Setup
+
+### Connection String (not Instrumentation Key)
+```csharp
+// appsettings.json — use connection string, not key
+{
+  "ApplicationInsights": {
+    "ConnectionString": "InstrumentationKey=..." // from Key Vault
+  }
+}
+
+// Program.cs
+builder.Services.AddApplicationInsightsTelemetry(
+    builder.Configuration["ApplicationInsights:ConnectionString"]);
+```
+
+### Sampling Configuration
+```csharp
+builder.Services.Configure<TelemetryConfiguration>(config =>
+{
+    var sampler = new AdaptiveSamplingTelemetryProcessor(null!);
+    sampler.MaxTelemetryItemsPerSecond = 5; // Limit volume
+    sampler.ExcludedTypes = "Request"; // Don't sample requests
+    config.TelemetryProcessorChainBuilder.Use(_ => sampler).Build();
+});
+```
+
+### Dependency Tracking
+```csharp
+// Auto-tracked: HTTP, SQL, Azure SDK calls
+// Manual tracking for custom operations:
+using var operation = telemetryClient.StartOperation<DependencyTelemetry>("ServiceBus.Send");
+operation.Telemetry.Type = "Azure Service Bus";
+operation.Telemetry.Target = queueName;
+try
+{
+    await sender.SendMessageAsync(message);
+    operation.Telemetry.Success = true;
+}
+catch (Exception ex)
+{
+    operation.Telemetry.Success = false;
+    telemetryClient.TrackException(ex);
+    throw;
+}
+```
+
+## KQL Queries — Common Scenarios
+
+### Request Success Rate (last 24h)
+```kql
+requests
+| where timestamp > ago(24h)
+| summarize
+    total = count(),
+    failed = countif(success == false),
+    successRate = round(100.0 * countif(success == true) / count(), 2)
+| project total, failed, successRate
+```
+
+### Slow Requests (> 2s)
+```kql
+requests
+| where duration > 2000 and timestamp > ago(1h)
+| project timestamp, name, url, duration, resultCode, cloud_RoleInstance
+| order by duration desc
+| take 20
+```
+
+### Exception Summary
+```kql
+exceptions
+| where timestamp > ago(24h)
+| summarize count() by type, outerMessage
+| order by count_ desc
+| take 10
+```
+
+### Dependency Failures
+```kql
+dependencies
+| where success == false and timestamp > ago(1h)
+| project timestamp, name, type, target, duration, resultCode, data
+| order by timestamp desc
+```
+
+### User Activity Heatmap
+```kql
+customEvents
+| where timestamp > ago(7d)
+| summarize events = count() by bin(timestamp, 1h), name
+| render timechart
+```
+
+## Alerting Rules
+
+| Alert | Condition | Severity |
+|-------|-----------|----------|
+| High error rate | `requests` failure rate > 5% for 5 min | Critical |
+| Slow response | P95 latency > 3s for 10 min | Warning |
+| Exception spike | Exception count > 100/min | Critical |
+| Dependency failure | Any dependency > 10 failures/min | Warning |
+
+## Dashboard Required Sections
+- Request volume + success rate (1h/24h/7d)
+- Top slow endpoints
+- Exception breakdown by type
+- Dependency health grid
+- Active user count