@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

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

@@ -1,366 +0,0 @@
-# .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/framework/standards/backend/dotnet/core.md

@@ -1,117 +0,0 @@
-# .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*