@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/standards/backend/dotnet/async.md

@@ -0,0 +1,366 @@
+# .NET Async/Await Standards
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** async, await, task, asynchronous, threading
+> **Load When:** always
+
+Asynchronous programming patterns for .NET applications
+
+---
+
+## Basic Patterns
+
+### Async Method Signatures
+
+```csharp
+// ✅ CORRECT
+public async Task<User> GetUserAsync(int id)
+{
+    return await _repository.GetByIdAsync(id);
+}
+
+// ✅ CORRECT (no return value)
+public async Task DeleteUserAsync(int id)
+{
+    await _repository.DeleteAsync(id);
+}
+
+// ❌ WRONG (async void - only for event handlers)
+public async void ProcessOrder(int orderId) // Don't do this!
+{
+    await _orderService.ProcessAsync(orderId);
+}
+```
+
+### Naming Convention
+
+**All async methods MUST end with `Async` suffix**
+
+```csharp
+// ✅ CORRECT
+Task<Order> GetOrderAsync(int id)
+Task SaveChangesAsync()
+Task<bool> ValidateAsync(string input)
+
+// ❌ WRONG
+Task<Order> GetOrder(int id)
+Task SaveChanges()
+```
+
+---
+
+## CancellationToken
+
+### Always Accept CancellationToken
+
+```csharp
+// ✅ CORRECT
+public async Task<User> GetUserAsync(int id, CancellationToken ct = default)
+{
+    return await _context.Users
+        .Where(u => u.Id == id)
+        .FirstOrDefaultAsync(ct);
+}
+
+// ✅ CORRECT (in controller)
+[HttpGet("{id}")]
+public async Task<IActionResult> GetUser(int id, CancellationToken ct)
+{
+    var user = await _userService.GetUserAsync(id, ct);
+    return Ok(user);
+}
+```
+
+### Pass CancellationToken Down
+
+```csharp
+public async Task<Order> ProcessOrderAsync(int orderId, CancellationToken ct = default)
+{
+    // Pass ct to all async calls
+    var order = await _repository.GetByIdAsync(orderId, ct);
+    await _paymentService.ChargeAsync(order, ct);
+    await _emailService.SendConfirmationAsync(order, ct);
+
+    return order;
+}
+```
+
+---
+
+## ConfigureAwait
+
+### Library Code
+
+Use `ConfigureAwait(false)` in library/infrastructure code:
+
+```csharp
+// Infrastructure layer
+public async Task<User> GetByIdAsync(int id)
+{
+    return await _context.Users
+        .FindAsync(id)
+        .ConfigureAwait(false); // ✅ Library code
+}
+```
+
+### Application Code
+
+DON'T use `ConfigureAwait(false)` in application/API layer:
+
+```csharp
+// Controller/Service layer
+public async Task<IActionResult> GetUser(int id)
+{
+    // ✅ CORRECT (no ConfigureAwait in app layer)
+    var user = await _userService.GetByIdAsync(id);
+    return Ok(user);
+}
+```
+
+---
+
+## Async Best Practices
+
+### DO
+
+✅ **Use async all the way**
+
+```csharp
+// ✅ CORRECT
+public async Task<ActionResult> CreateOrder()
+{
+    var order = await _service.CreateOrderAsync();
+    await _context.SaveChangesAsync();
+    return Ok(order);
+}
+```
+
+✅ **Use Task.WhenAll for parallel operations**
+
+```csharp
+// ✅ CORRECT (parallel)
+var userTask = _userService.GetUserAsync(userId);
+var ordersTask = _orderService.GetOrdersAsync(userId);
+var settingsTask = _settingsService.GetSettingsAsync(userId);
+
+await Task.WhenAll(userTask, ordersTask, settingsTask);
+
+var user = await userTask;
+var orders = await ordersTask;
+var settings = await settingsTask;
+```
+
+✅ **Return Task directly when no await needed**
+
+```csharp
+// ✅ CORRECT (no unnecessary async/await)
+public Task<User> GetUserAsync(int id)
+{
+    return _repository.GetByIdAsync(id); // No await needed
+}
+```
+
+### DON'T
+
+❌ **Don't use async void (except event handlers)**
+
+```csharp
+// ❌ WRONG
+public async void ProcessOrder(int id)
+{
+    await _service.ProcessAsync(id); // Exceptions swallowed!
+}
+
+// ✅ CORRECT
+public async Task ProcessOrderAsync(int id)
+{
+    await _service.ProcessAsync(id);
+}
+```
+
+❌ **Don't use .Result or .Wait()**
+
+```csharp
+// ❌ WRONG (blocks thread, risk of deadlock)
+var user = _userService.GetUserAsync(id).Result;
+_orderService.ProcessAsync(orderId).Wait();
+
+// ✅ CORRECT
+var user = await _userService.GetUserAsync(id);
+await _orderService.ProcessAsync(orderId);
+```
+
+❌ **Don't create unnecessary tasks**
+
+```csharp
+// ❌ WRONG
+public async Task<int> GetCountAsync()
+{
+    return await Task.FromResult(_items.Count); // Unnecessary!
+}
+
+// ✅ CORRECT
+public Task<int> GetCountAsync()
+{
+    return Task.FromResult(_items.Count); // Or just return synchronously
+}
+```
+
+---
+
+## Async Patterns
+
+### Pattern: Retry with Exponential Backoff
+
+```csharp
+public async Task<T> RetryAsync<T>(
+    Func<Task<T>> operation,
+    int maxRetries = 3,
+    CancellationToken ct = default)
+{
+    for (int i = 0; i < maxRetries; i++)
+    {
+        try
+        {
+            return await operation();
+        }
+        catch (Exception) when (i < maxRetries - 1)
+        {
+            var delay = TimeSpan.FromSeconds(Math.Pow(2, i)); // 1s, 2s, 4s
+            await Task.Delay(delay, ct);
+        }
+    }
+
+    throw new InvalidOperationException($"Failed after {maxRetries} retries");
+}
+```
+
+### Pattern: Timeout
+
+```csharp
+public async Task<User> GetUserWithTimeoutAsync(int id)
+{
+    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+
+    try
+    {
+        return await _repository.GetByIdAsync(id, cts.Token);
+    }
+    catch (OperationCanceledException)
+    {
+        throw new TimeoutException("Operation timed out after 5 seconds");
+    }
+}
+```
+
+### Pattern: Background Work (Fire and Forget)
+
+```csharp
+// ❌ WRONG (async void)
+public async void LogAsync(string message)
+{
+    await _logger.WriteAsync(message);
+}
+
+// ✅ CORRECT (use background service or Hangfire)
+public Task LogAsync(string message)
+{
+    _ = Task.Run(async () =>
+    {
+        try
+        {
+            await _logger.WriteAsync(message);
+        }
+        catch (Exception ex)
+        {
+            // Handle exceptions
+        }
+    });
+
+    return Task.CompletedTask;
+}
+```
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Mixing Sync and Async
+
+```csharp
+// ❌ WRONG
+public User GetUser(int id)
+{
+    return _repository.GetByIdAsync(id).Result; // Deadlock risk!
+}
+
+// ✅ CORRECT
+public async Task<User> GetUserAsync(int id)
+{
+    return await _repository.GetByIdAsync(id);
+}
+```
+
+### Mistake 2: Not Awaiting in Loop
+
+```csharp
+// ❌ WRONG (sequential, slow)
+foreach (var id in userIds)
+{
+    await _service.ProcessAsync(id);
+}
+
+// ✅ CORRECT (parallel)
+var tasks = userIds.Select(id => _service.ProcessAsync(id));
+await Task.WhenAll(tasks);
+```
+
+### Mistake 3: Unnecessary Async/Await
+
+```csharp
+// ❌ WRONG (extra state machine)
+public async Task<User> GetUserAsync(int id)
+{
+    return await _repository.GetByIdAsync(id);
+}
+
+// ✅ CORRECT (no async needed)
+public Task<User> GetUserAsync(int id)
+{
+    return _repository.GetByIdAsync(id);
+}
+```
+
+---
+
+## Blazor-Specific
+
+### Async in OnInitializedAsync
+
+```csharp
+// ✅ CORRECT
+protected override async Task OnInitializedAsync()
+{
+    users = await UserService.GetUsersAsync();
+    StateHasChanged(); // Optional, called automatically
+}
+```
+
+### Async Event Handlers
+
+```csharp
+// ✅ CORRECT
+private async Task HandleSubmitAsync()
+{
+    await OrderService.CreateAsync(order);
+    NavigationManager.NavigateTo("/orders");
+}
+
+// In Razor:
+<button @onclick="HandleSubmitAsync">Submit</button>
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/backend/dotnet/core.md

@@ -0,0 +1,117 @@
+# .NET 10 Package Compatibility Matrix
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** dotnet, net10, csharp, patterns, core
+> **Load When:** always
+
+## Package Matrix
+
+| Package | .NET 9 (Last) | .NET 10 (Min) | Breaking Changes |
+|---------|---------------|---------------|------------------|
+| **MudBlazor** | 6.21.0 | **>= 8.15.0** | Theme API, generics, events |
+| **FluentUI.Blazor** | 4.x | **>= 5.0.0** | Component params, icon system |
+| **Hangfire.AspNetCore** | 1.8.x | **>= 1.8.22** | None (TFM update only) |
+| **EF Core** | 9.x | **10.0.0** | Vector search, primitive collections |
+| **Azure.Storage.Blobs** | 12.19.x | **>= 12.20.0** | None |
+| **Agent Framework** | N/A | **>= 1.0.0** | Replaces Semantic Kernel |
+
+---
+
+## MudBlazor 6.x → 8.x
+
+```csharp
+// Theme API
+// WRONG (v6): new MudTheme { Palette = new Palette { Primary = "#7C3AED" } }
+// CORRECT (v8):
+var theme = new MudTheme
+{
+    PaletteLight = new PaletteLight { Primary = "#7C3AED" },
+    PaletteDark = new PaletteDark { Primary = "#9D74F2" }
+};
+
+// Generic components
+// WRONG (v6): <MudChip OnClose="HandleClose">
+// CORRECT (v8): <MudChip T="string" Closed="HandleClosed">Tag</MudChip>
+
+// Dialog
+// WRONG (v6): <MudDialog DisableBackdropClick="true">
+// CORRECT (v8): <MudDialog BackdropClick="() => {}">
+```
+
+**Migration:** `Palette` → `PaletteLight`/`PaletteDark`, `OnClose` → `Closed`, `DisableBackdropClick` → `BackdropClick`
+
+---
+
+## Fluent UI 4.x → 5.x
+
+```csharp
+// Component params: Appearance now requires @
+// WRONG (v4): <FluentButton Appearance="Appearance.Accent">
+// CORRECT (v5): <FluentButton Appearance="@Appearance.Accent">
+
+// Icon system
+// WRONG (v4): <FluentIcon Name="@FluentIcons.Add" />
+// CORRECT (v5): <FluentIcon Icon="@Icons.Add" />
+```
+
+> **Ref:** `fluent-ui-blazor.md` for full Fluent UI API reference.
+
+---
+
+## EF Core 10 New Features
+
+```csharp
+// Vector search (Azure SQL)
+[Column(TypeName = "vector(384)")]
+public float[] Embedding { get; set; } = Array.Empty<float>();
+
+var similar = await context.Products
+    .OrderBy(p => EF.Functions.VectorDistance(p.Embedding, searchEmbedding))
+    .Take(10).ToListAsync();
+
+// Primitive collections (stored as JSON)
+public List<string> Roles { get; set; } = new();
+```
+
+**Breaking:** Required navigation properties now throw if not loaded. Query splitting behavior changed.
+
+---
+
+## Agent Framework (replaces Semantic Kernel)
+
+```csharp
+// DEPRECATED (Semantic Kernel)
+var kernel = Kernel.CreateBuilder().AddAzureOpenAIChatCompletion(...).Build();
+
+// NEW (Microsoft Agent Framework)
+var agent = new Agent().WithModel("gpt-4").WithInstructions("...");
+var response = await agent.RunAsync("Summarize this text...");
+```
+
+> **Ref:** `stacks/blazor-azure/.morph/standards/agent-framework-setup.md` for full migration guide.
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "JS interop not initialized" | Incompatible UI lib version | Upgrade to .NET 10 compatible version |
+| "Cannot find PaletteLight" | MudBlazor 6.x API with 8.x | Use `PaletteLight`/`PaletteDark` |
+| CS0618 deprecation warnings | Old API still compiles | Migrate to new API |
+
+## Migration Checklist
+
+- [ ] Git commit/branch (backup)
+- [ ] `TargetFramework` → `net10.0`
+- [ ] Update all `Microsoft.*` to 10.x
+- [ ] EF Core → 10.0.x
+- [ ] MudBlazor → 8.15.0+ (if used): theme, generics, events
+- [ ] Fluent UI → 5.0.0+ (if used): params, icons
+- [ ] Build succeeds + all tests pass
+- [ ] UI renders correctly
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*