@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/framework/standards/data/nosql/cache/redis.md

@@ -1,97 +1,106 @@
-# Data Standard: Redis Cache (Azure Cache for Redis)
-
-## Overview
-Distributed cache for session data, rate limiting, and frequently-read data.
-
-## Setup
-```xml
-<PackageReference Include="StackExchange.Redis" Version="2.*" />
-<PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="9.*" />
-```
-
-```csharp
-// Program.cs
-builder.Services.AddStackExchangeRedisCache(opts =>
-{
-    opts.Configuration = config["Redis:ConnectionString"]; // from Key Vault
-    opts.InstanceName = "myapp:"; // Prefix to avoid key collisions
-});
-```
-
-## Cache-Aside Pattern
-```csharp
-public class CachedProductService : IProductService
-{
-    private readonly IDistributedCache _cache;
-    private readonly IProductRepository _repository;
-
-    public async Task<Product?> GetAsync(Guid id, CancellationToken ct = default)
-    {
-        var cacheKey = $"product:{id}";
-
-        // Try cache first
-        var cached = await _cache.GetStringAsync(cacheKey, ct);
-        if (cached != null)
-            return JsonSerializer.Deserialize<Product>(cached);
-
-        // Cache miss → read from DB
-        var product = await _repository.GetAsync(id, ct);
-        if (product == null) return null;
-
-        // Cache with TTL
-        await _cache.SetStringAsync(cacheKey,
-            JsonSerializer.Serialize(product),
-            new DistributedCacheEntryOptions
-            {
-                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(15),
-                SlidingExpiration = TimeSpan.FromMinutes(5)
-            }, ct);
-
-        return product;
-    }
-
-    public async Task InvalidateAsync(Guid id, CancellationToken ct = default)
-        => await _cache.RemoveAsync($"product:{id}", ct);
-}
-```
-
-## TTL Strategy
-| Data Type | TTL | Rationale |
-|-----------|-----|-----------|
-| User session | 30 min sliding | Active session window |
-| Product catalog | 15 min absolute | Inventory changes |
-| Rate limit counters | 1 min | Per-minute limiting |
-| Computed aggregates | 1 hour | Expensive query results |
-| Reference data | 24 hours | Config rarely changes |
-
-## Key Naming Convention
-```
-{service}:{entity}:{id}
-{service}:{entity}:list:{filter}
-{service}:ratelimit:{userId}:{endpoint}
-
-Examples:
-  product:detail:550e8400-e29b-41d4-a716
-  product:list:category:electronics
-  auth:ratelimit:user123:login
-```
-
-## Rate Limiting Pattern
-```csharp
-public async Task<bool> IsRateLimitedAsync(string userId, string action, int maxPerMinute)
-{
-    var key = $"ratelimit:{action}:{userId}:{DateTime.UtcNow:yyyyMMddHHmm}";
-    var db = _redis.GetDatabase();
-
-    var count = await db.StringIncrementAsync(key);
-    if (count == 1) await db.KeyExpireAsync(key, TimeSpan.FromMinutes(1));
-
-    return count > maxPerMinute;
-}
-```
-
-## Anti-Patterns
-- Never cache sensitive data (passwords, tokens, PII) without encryption
-- Never use Redis as primary store — it's a cache, not a database
-- Never omit TTL — unbounded keys fill memory
-- Never catch RedisException silently — degrade gracefully to DB
+# Data Standard: Redis Cache (Azure Cache for Redis)
+
+> **Scope:** data-nosql-cache
+> **Layer:** 2
+> **Keywords:** redis, cache, distributed-cache, session, rate-limiting, stackexchange-redis, azure-cache
+> **Load When:** caching, session storage, or rate limiting is in scope
+
+**Verified against:** .NET 10 + StackExchange.Redis 2.x + Microsoft.Extensions.Caching.StackExchangeRedis. Last-verified: 2026-05-20.
+
+---
+
+## Overview
+Distributed cache for session data, rate limiting, and frequently-read data.
+
+## Setup
+```xml
+<PackageReference Include="StackExchange.Redis" Version="2.*" />
+<PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="9.*" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddStackExchangeRedisCache(opts =>
+{
+    opts.Configuration = config["Redis:ConnectionString"]; // from Key Vault
+    opts.InstanceName = "myapp:"; // Prefix to avoid key collisions
+});
+```
+
+## Cache-Aside Pattern
+```csharp
+public class CachedProductService : IProductService
+{
+    private readonly IDistributedCache _cache;
+    private readonly IProductRepository _repository;
+
+    public async Task<Product?> GetAsync(Guid id, CancellationToken ct = default)
+    {
+        var cacheKey = $"product:{id}";
+
+        // Try cache first
+        var cached = await _cache.GetStringAsync(cacheKey, ct);
+        if (cached != null)
+            return JsonSerializer.Deserialize<Product>(cached);
+
+        // Cache miss → read from DB
+        var product = await _repository.GetAsync(id, ct);
+        if (product == null) return null;
+
+        // Cache with TTL
+        await _cache.SetStringAsync(cacheKey,
+            JsonSerializer.Serialize(product),
+            new DistributedCacheEntryOptions
+            {
+                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(15),
+                SlidingExpiration = TimeSpan.FromMinutes(5)
+            }, ct);
+
+        return product;
+    }
+
+    public async Task InvalidateAsync(Guid id, CancellationToken ct = default)
+        => await _cache.RemoveAsync($"product:{id}", ct);
+}
+```
+
+## TTL Strategy
+| Data Type | TTL | Rationale |
+|-----------|-----|-----------|
+| User session | 30 min sliding | Active session window |
+| Product catalog | 15 min absolute | Inventory changes |
+| Rate limit counters | 1 min | Per-minute limiting |
+| Computed aggregates | 1 hour | Expensive query results |
+| Reference data | 24 hours | Config rarely changes |
+
+## Key Naming Convention
+```
+{service}:{entity}:{id}
+{service}:{entity}:list:{filter}
+{service}:ratelimit:{userId}:{endpoint}
+
+Examples:
+  product:detail:550e8400-e29b-41d4-a716
+  product:list:category:electronics
+  auth:ratelimit:user123:login
+```
+
+## Rate Limiting Pattern
+```csharp
+public async Task<bool> IsRateLimitedAsync(string userId, string action, int maxPerMinute)
+{
+    var key = $"ratelimit:{action}:{userId}:{DateTime.UtcNow:yyyyMMddHHmm}";
+    var db = _redis.GetDatabase();
+
+    var count = await db.StringIncrementAsync(key);
+    if (count == 1) await db.KeyExpireAsync(key, TimeSpan.FromMinutes(1));
+
+    return count > maxPerMinute;
+}
+```
+
+## Anti-Patterns
+- Never cache sensitive data (passwords, tokens, PII) without encryption
+- Never use Redis as primary store — it's a cache, not a database
+- Never omit TTL — unbounded keys fill memory
+- Never catch RedisException silently — degrade gracefully to DB

package/framework/standards/data/nosql/cosmos-db.md

@@ -1,118 +1,127 @@
-# Data Standard: Azure Cosmos DB
-
-## Overview
-NoSQL document database — use for high-throughput, globally distributed, or schema-flexible data.
-
-## When to Use Cosmos DB
-✅ Event store (append-only, high write throughput)
-✅ User activity/session data (variable schema)
-✅ Multi-region writes required
-✅ JSON documents with flexible schema
-❌ Relational data with complex joins (use Azure SQL)
-❌ Small datasets (cost inefficient)
-
-## Container Design
-```json
-{
-  "partitionKey": "/tenantId",
-  "indexingPolicy": {
-    "includedPaths": [{ "path": "/*" }],
-    "excludedPaths": [
-      { "path": "/largePayload/*" },
-      { "path": "/_etag/?" }
-    ]
-  }
-}
-```
-
-### Partition Key Strategy
-- High cardinality: userId, tenantId, orderId
-- Even distribution: avoid hot partitions (e.g., /status = "active" for 90% of docs)
-- Query alignment: partition key should appear in most queries
-
-## SDK Setup
-```csharp
-// Program.cs
-builder.Services.AddSingleton(sp =>
-    new CosmosClient(
-        config["CosmosDb:ConnectionString"],
-        new CosmosClientOptions
-        {
-            SerializerOptions = new CosmosSerializationOptions
-            {
-                PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
-            },
-            ApplicationName = "MyApp"
-        }));
-
-builder.Services.AddSingleton<ICosmosRepository<Order>>(sp =>
-    new CosmosRepository<Order>(
-        sp.GetRequiredService<CosmosClient>(),
-        config["CosmosDb:DatabaseId"],
-        "orders"));
-```
-
-## Repository Pattern
-```csharp
-public class CosmosRepository<T> where T : CosmosDocument
-{
-    private readonly Container _container;
-
-    public async Task<T?> GetAsync(string id, string partitionKey)
-    {
-        try
-        {
-            var response = await _container.ReadItemAsync<T>(id, new PartitionKey(partitionKey));
-            return response.Resource;
-        }
-        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
-        {
-            return null;
-        }
-    }
-
-    public async Task<IReadOnlyList<T>> QueryAsync(string sql, Dictionary<string, object>? parameters = null)
-    {
-        var query = new QueryDefinition(sql);
-        if (parameters != null)
-            foreach (var (k, v) in parameters) query = query.WithParameter(k, v);
-
-        var results = new List<T>();
-        using var feed = _container.GetItemQueryIterator<T>(query);
-        while (feed.HasMoreResults)
-        {
-            var page = await feed.ReadNextAsync();
-            results.AddRange(page);
-        }
-        return results;
-    }
-
-    public async Task UpsertAsync(T document)
-        => await _container.UpsertItemAsync(document, new PartitionKey(document.PartitionKey));
-}
-```
-
-## Document Base Class
-```csharp
-public abstract class CosmosDocument
-{
-    [JsonPropertyName("id")]
-    public string Id { get; set; } = Guid.NewGuid().ToString();
-
-    [JsonPropertyName("_partitionKey")]
-    public abstract string PartitionKey { get; }
-
-    [JsonPropertyName("type")]
-    public string Type => GetType().Name;
-
-    [JsonPropertyName("createdAt")]
-    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
-}
-```
-
-## Cost Optimization
-- Enable TTL on transient data (session, temp tokens)
-- Use serverless mode for dev/test environments
-- Index only queried paths (exclude large blobs)
-- Batch operations with TransactionalBatch for same partition
-- Use bulk execution for large imports
+# Data Standard: Azure Cosmos DB
+
+> **Scope:** data-nosql
+> **Layer:** 2
+> **Keywords:** cosmos-db, nosql, document-database, event-store, partition-key, azure-cosmos
+> **Load When:** a NoSQL document store, event store, or globally distributed data is in scope
+
+**Verified against:** .NET 10 + Microsoft.Azure.Cosmos SDK v3. Last-verified: 2026-05-20.
+
+---
+
+## Overview
+NoSQL document database — use for high-throughput, globally distributed, or schema-flexible data.
+
+## When to Use Cosmos DB
+✅ Event store (append-only, high write throughput)
+✅ User activity/session data (variable schema)
+✅ Multi-region writes required
+✅ JSON documents with flexible schema
+❌ Relational data with complex joins (use Azure SQL)
+❌ Small datasets (cost inefficient)
+
+## Container Design
+```json
+{
+  "partitionKey": "/tenantId",
+  "indexingPolicy": {
+    "includedPaths": [{ "path": "/*" }],
+    "excludedPaths": [
+      { "path": "/largePayload/*" },
+      { "path": "/_etag/?" }
+    ]
+  }
+}
+```
+
+### Partition Key Strategy
+- High cardinality: userId, tenantId, orderId
+- Even distribution: avoid hot partitions (e.g., /status = "active" for 90% of docs)
+- Query alignment: partition key should appear in most queries
+
+## SDK Setup
+```csharp
+// Program.cs
+builder.Services.AddSingleton(sp =>
+    new CosmosClient(
+        config["CosmosDb:ConnectionString"],
+        new CosmosClientOptions
+        {
+            SerializerOptions = new CosmosSerializationOptions
+            {
+                PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
+            },
+            ApplicationName = "MyApp"
+        }));
+
+builder.Services.AddSingleton<ICosmosRepository<Order>>(sp =>
+    new CosmosRepository<Order>(
+        sp.GetRequiredService<CosmosClient>(),
+        config["CosmosDb:DatabaseId"],
+        "orders"));
+```
+
+## Repository Pattern
+```csharp
+public class CosmosRepository<T> where T : CosmosDocument
+{
+    private readonly Container _container;
+
+    public async Task<T?> GetAsync(string id, string partitionKey)
+    {
+        try
+        {
+            var response = await _container.ReadItemAsync<T>(id, new PartitionKey(partitionKey));
+            return response.Resource;
+        }
+        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+        {
+            return null;
+        }
+    }
+
+    public async Task<IReadOnlyList<T>> QueryAsync(string sql, Dictionary<string, object>? parameters = null)
+    {
+        var query = new QueryDefinition(sql);
+        if (parameters != null)
+            foreach (var (k, v) in parameters) query = query.WithParameter(k, v);
+
+        var results = new List<T>();
+        using var feed = _container.GetItemQueryIterator<T>(query);
+        while (feed.HasMoreResults)
+        {
+            var page = await feed.ReadNextAsync();
+            results.AddRange(page);
+        }
+        return results;
+    }
+
+    public async Task UpsertAsync(T document)
+        => await _container.UpsertItemAsync(document, new PartitionKey(document.PartitionKey));
+}
+```
+
+## Document Base Class
+```csharp
+public abstract class CosmosDocument
+{
+    [JsonPropertyName("id")]
+    public string Id { get; set; } = Guid.NewGuid().ToString();
+
+    [JsonPropertyName("_partitionKey")]
+    public abstract string PartitionKey { get; }
+
+    [JsonPropertyName("type")]
+    public string Type => GetType().Name;
+
+    [JsonPropertyName("createdAt")]
+    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
+}
+```
+
+## Cost Optimization
+- Enable TTL on transient data (session, temp tokens)
+- Use serverless mode for dev/test environments
+- Index only queried paths (exclude large blobs)
+- Batch operations with TransactionalBatch for same partition
+- Use bulk execution for large imports