@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/analyzing-dotnet-performance/references/async-patterns.md

@@ -0,0 +1,122 @@
+# Async & Concurrency Patterns
+
+## Contents
+
+- Don't Expose Async Wrappers for Sync Methods
+- Don't Expose Sync Wrappers for Async Methods
+- Use ValueTask for Hot Paths with Frequent Sync Completion
+- Use Channels for Producer/Consumer
+- Avoid False Sharing with Thread-Local State
+- Detection
+  - Patterns Requiring Manual Review
+
+### Don't Expose Async Wrappers for Sync Methods
+🟡 **AVOID** wrapping sync methods with `Task.Run` in libraries | .NET Core+
+
+❌
+```csharp
+public Task<int> ComputeHashAsync(byte[] data) =>
+    Task.Run(() => ComputeHash(data));
+```
+✅
+```csharp
+public int ComputeHash(byte[] data) { /* CPU-bound work */ }
+// Consumer decides: var hash = await Task.Run(() => lib.ComputeHash(data));
+```
+
+**Impact: Eliminates unnecessary thread pool queue/dequeue overhead per call.**
+
+### Don't Expose Sync Wrappers for Async Methods
+🟡 **AVOID** creating sync wrappers that block on async implementations | .NET Core+
+
+❌
+```csharp
+public string GetData() => GetDataAsync().Result;
+```
+✅
+```csharp
+public async Task<string> GetDataAsync() { /* ... */ }
+```
+
+**Impact: Prevents deadlocks and thread pool starvation from hidden sync-over-async blocking.**
+
+### Use ValueTask for Hot Paths with Frequent Sync Completion
+🟡 **DO** use `ValueTask<T>` on hot paths where sync completion is common | .NET Core 2.1+
+
+❌
+```csharp
+public async Task<int> ReadAsync(Memory<byte> buffer)
+{
+    if (_bufferedCount > 0)
+        return ReadFromBuffer(buffer.Span);
+    return await ReadAsyncCore(buffer);
+}
+```
+✅
+```csharp
+public ValueTask<int> ReadAsync(Memory<byte> buffer)
+{
+    if (_bufferedCount > 0)
+        return new ValueTask<int>(ReadFromBuffer(buffer.Span));
+    return new ValueTask<int>(ReadAsyncCore(buffer));
+}
+```
+
+**Impact: Eliminates Task\<T\> allocation on synchronous completion — the struct stores results inline.**
+
+### Use Channels for Producer/Consumer
+🟡 **DO** use `System.Threading.Channels` for producer-consumer patterns | .NET Core 3.0+
+
+❌
+```csharp
+var queue = new BlockingCollection<WorkItem>();
+var item = queue.Take();
+```
+✅
+```csharp
+var channel = Channel.CreateUnbounded<WorkItem>();
+
+// Producer
+await channel.Writer.WriteAsync(item);
+
+// Consumer
+await foreach (var item in channel.Reader.ReadAllAsync())
+    Process(item);
+```
+
+**Impact: ~25% faster, ~95% fewer GC collections vs manual approaches.**
+
+### Avoid False Sharing with Thread-Local State
+🟡 **AVOID** adjacent mutable fields written by different threads | .NET 7+
+
+❌
+```csharp
+class SharedCounters
+{
+    public long Counter1;
+    public long Counter2;
+}
+```
+✅
+```csharp
+[StructLayout(LayoutKind.Explicit, Size = 128)]
+struct PaddedCounter
+{
+    [FieldOffset(0)] public long Value;
+}
+```
+
+**Impact: Eliminates cross-core cache invalidation — can improve multi-threaded throughput by 10x+.**
+
+## Detection
+
+Scan recipes for async anti-patterns. Run these and report exact counts.
+
+```bash
+# async void methods (correctness issue — crashes on exception)
+grep -rn --include='*.cs' 'async void' --exclude-dir=bin --exclude-dir=obj . | grep -v 'event' | wc -l
+```
+
+### Patterns Requiring Manual Review
+
+- **Sync-over-async** (`.Result`, `.Wait()`): `.Result` matches any property named Result — needs type context to confirm it's `Task.Result`

package/package/corpus/skills/analyzing-dotnet-performance/references/collections-and-linq.md

@@ -0,0 +1,220 @@
+# Collections & LINQ Patterns
+
+## Contents
+
+- Use FrozenDictionary/FrozenSet for Read-Heavy Lookup Tables
+- Use Dictionary Alternate Lookup for Span-Based Keys
+- Use CollectionsMarshal.GetValueRefOrNullRef for Lookup-and-Update
+- Use Collection Expressions [] for Zero-Allocation Span Creation
+- Use EnsureCapacity on List/Stack/Queue Before Bulk Adds
+- Use TryGetNonEnumeratedCount for Pre-Sizing
+- Hoist Static Data Out of Method Bodies
+- Add Overloads to Avoid params Array Allocation
+- Detection
+  - Patterns Requiring Manual Review
+
+### Use FrozenDictionary/FrozenSet for Read-Heavy Lookup Tables
+🟡 **DO** use `FrozenDictionary`/`FrozenSet` for collections created once and read many times | .NET 8+
+
+❌
+```csharp
+private static readonly Dictionary<string, int> s_statusCodes = new()
+{
+    ["OK"] = 200, ["NotFound"] = 404, ["InternalServerError"] = 500
+};
+```
+✅
+```csharp
+private static readonly FrozenDictionary<string, int> s_statusCodes =
+    new Dictionary<string, int>
+    {
+        ["OK"] = 200, ["NotFound"] = 404, ["InternalServerError"] = 500
+    }.ToFrozenDictionary();
+```
+
+**Impact: ~50% faster lookups than Dictionary, ~14x faster than ImmutableDictionary.**
+
+### Use Dictionary Alternate Lookup for Span-Based Keys
+🟡 **DO** use `GetAlternateLookup<ReadOnlySpan<char>>()` to avoid string allocation on lookups | .NET 9+
+
+❌
+```csharp
+string key = headerLine.Substring(0, colonIndex);
+if (s_dict.TryGetValue(key, out int value)) { /* ... */ }
+```
+✅
+```csharp
+var lookup = s_dict.GetAlternateLookup<ReadOnlySpan<char>>();
+ReadOnlySpan<char> key = headerLine.AsSpan(0, colonIndex);
+if (lookup.TryGetValue(key, out int value)) { }
+```
+
+**Impact: Avoids string allocation per lookup — especially valuable in parser/protocol hot paths.**
+
+### Use CollectionsMarshal.GetValueRefOrNullRef for Lookup-and-Update
+🟡 **DO** use `CollectionsMarshal.GetValueRefOrAddDefault` for dictionary update patterns | .NET 6+
+
+❌
+```csharp
+_counts.TryGetValue(key, out int count);
+_counts[key] = count + 1;
+```
+✅
+```csharp
+ref int count = ref CollectionsMarshal.GetValueRefOrAddDefault(_counts, key, out _);
+count++;
+```
+
+**Impact: ~48% faster for lookup-and-update patterns (95µs → 49µs).**
+
+### Use Collection Expressions [] for Zero-Allocation Span Creation
+🟡 **DO** use collection expressions for `Span<T>` targets | C# 12 / .NET 8+
+
+❌
+```csharp
+int[] values = new int[] { a, b, c, d };
+```
+✅
+```csharp
+Span<int> values = [a, b, c, d];
+ReadOnlySpan<int> daysInMonth = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+```
+
+**Impact: Zero heap allocation for span-targeted collection expressions.**
+
+### Use EnsureCapacity on List/Stack/Queue Before Bulk Adds
+🟡 **DO** call `EnsureCapacity` before bulk insertions | .NET 6+
+
+❌
+```csharp
+var list = new List<int>();
+for (int i = 0; i < 10000; i++)
+    list.Add(i);
+```
+✅
+```csharp
+var list = new List<int>();
+list.EnsureCapacity(10000);
+for (int i = 0; i < 10000; i++)
+    list.Add(i);
+```
+
+**Impact: Reduces reallocations and array copies during bulk operations.**
+
+### Use TryGetNonEnumeratedCount for Pre-Sizing
+🟡 **DO** use `TryGetNonEnumeratedCount` to pre-size destination collections | .NET 6+
+
+❌
+```csharp
+var results = new List<int>();
+foreach (var item in source)
+    results.Add(Transform(item));
+```
+✅
+```csharp
+var results = source.TryGetNonEnumeratedCount(out int count)
+    ? new List<int>(count)
+    : new List<int>();
+foreach (var item in source)
+    results.Add(Transform(item));
+```
+
+**Impact: Avoids O(n) enumeration for counting; eliminates resizing allocations.**
+
+### Hoist Static Data Out of Method Bodies
+🟡 **AVOID** creating collections with static/deterministic data inside method bodies | .NET Core+
+
+❌
+```csharp
+public string Convert(long number)
+{
+    var groupsMap = new Dictionary<long, Func<long, string>>
+    {
+        { 1_000_000_000, n => $"{Convert(n)} billion" },
+        { 1_000_000, n => $"{Convert(n)} million" },
+        { 1_000, n => $"{Convert(n)} thousand" },
+    };
+}
+```
+✅
+```csharp
+private static readonly FrozenDictionary<long, Func<long, string>> s_groupsMap =
+    new Dictionary<long, Func<long, string>>
+    {
+        { 1_000_000_000, n => $"{Convert(n)} billion" },
+        { 1_000_000, n => $"{Convert(n)} million" },
+        { 1_000, n => $"{Convert(n)} thousand" },
+    }.ToFrozenDictionary();
+
+public string Convert(long number)
+{
+    // ... use s_groupsMap
+}
+```
+
+**Impact: Eliminates collection + internal storage + closure allocations per call. For a Dictionary with N entries, saves ~N+3 allocations per invocation.**
+
+### Add Overloads to Avoid params Array Allocation
+🟡 **DO** add 1- and 2-argument overloads for methods that accept `params T[]`, or use `params ReadOnlySpan<T>` on .NET 9+ | .NET Core+
+
+❌
+```csharp
+public static string Transform(this string input, params IStringTransformer[] transformers) =>
+    transformers.Aggregate(input, (current, t) => t.Transform(current));
+
+"hello".Transform(To.TitleCase);
+```
+✅
+```csharp
+// Option A: Explicit overloads for common arities
+public static string Transform(this string input, IStringTransformer transformer) =>
+    transformer.Transform(input);
+
+public static string Transform(this string input, IStringTransformer t1, IStringTransformer t2) =>
+    t2.Transform(t1.Transform(input));
+
+public static string Transform(this string input, params IStringTransformer[] transformers) =>
+    transformers.Aggregate(input, (current, t) => t.Transform(current));
+
+// Option B (.NET 9+ / C# 13): params ReadOnlySpan<T> — zero heap allocation
+public static string Transform(this string input, params ReadOnlySpan<IStringTransformer> transformers)
+{
+    foreach (var t in transformers)
+        input = t.Transform(input);
+    return input;
+}
+```
+
+**Impact: Eliminates one array allocation per call for the common 1- and 2-argument cases. `params ReadOnlySpan<T>` eliminates it for all arities.**
+
+## Detection
+
+Scan recipes for collection and LINQ anti-patterns. Run these and report exact counts.
+
+```bash
+# Static Dictionary not using FrozenDictionary (read-only after init)
+grep -rn --include='*.cs' 'static readonly Dictionary<' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# Static FrozenDictionary (already optimized — verify the inverse)
+grep -rn --include='*.cs' 'static readonly FrozenDictionary<' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# Per-call List allocation (inside method bodies, not static/readonly fields)
+grep -rn --include='*.cs' 'new List<' --exclude-dir=bin --exclude-dir=obj . | grep -v 'static\|readonly' | wc -l
+
+# Per-call Dictionary allocation (inside method bodies, not static/readonly fields)
+grep -rn --include='*.cs' 'new Dictionary<' --exclude-dir=bin --exclude-dir=obj . | grep -v 'static\|readonly' | wc -l
+
+# StringComparer.CurrentCulture usage (almost always wrong in library code — use Ordinal)
+grep -rn --include='*.cs' 'StringComparer.CurrentCulture' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# LINQ chains in extension/hot-path files (.Select, .Where, .Cast, .Take, .Aggregate)
+grep -rn --include='*.cs' -E '\.(Select|Where|Cast|Take|Aggregate)\(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```
+
+For the LINQ chain recipe: any hit in a file whose name ends in `Extensions.cs`, `Formatter.cs`, or implements a method called from a public extension method is a hot-path candidate. Inspect each hit in these files and flag LINQ chains that allocate delegates, enumerators, or intermediate collections on every call. Hits in localization converters or one-time initialization are lower priority.
+
+### Patterns Requiring Manual Review
+
+- **ContainsKey + indexer double-lookup**: Requires verifying the same key is used in a subsequent indexer access — multi-line/multi-statement context
+- **LINQ on hot paths**: The LINQ chain recipe above catches call sites, but distinguishing hot-path from cold-path requires context. Prioritize hits in `*Extensions.cs` and `*Formatter.cs` files, which are typically called on every user invocation
+- **`new Dictionary/List<` in method bodies vs fields**: The grep heuristic (`grep -v 'static\|readonly'`) catches most cases but may include false positives from field initializers without `static`/`readonly` — spot-check flagged lines

package/package/corpus/skills/analyzing-dotnet-performance/references/critical-patterns.md

@@ -0,0 +1,291 @@
+# Critical .NET Performance Anti-Patterns
+
+## Contents
+
+- Async / Tasks
+- Memory / Allocation
+- Strings
+- Regular Expressions
+- JSON Serialization
+- Networking
+- General
+- Detection
+
+17 patterns that cause deadlocks, order-of-magnitude regressions, or excessive allocations.
+
+## Async / Tasks
+
+### Never Block on Async (Sync-over-Async)
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+public string GetData()
+    => GetDataAsync().Result;
+```
+✅
+```csharp
+public async Task<string> GetDataAsync()
+    => await GetDataInternalAsync();
+```
+**Impact: Deadlocks or thread pool starvation; wastes threads, destroys scalability.**
+
+### Never Await a ValueTask Multiple Times
+🔴 **AVOID** | .NET Core 2.1+
+
+❌
+```csharp
+ValueTask<int> vt = SomeMethodAsync();
+int a = await vt;
+int b = await vt;
+```
+✅
+```csharp
+int result = await SomeMethodAsync();
+```
+**Impact: Undefined behavior — silent data corruption or exceptions.**
+
+## Memory / Allocation
+
+### Use Span\<T\> / AsSpan Instead of Substring for Slicing
+🔴 **DO** | .NET Core 2.1+
+
+❌
+```csharp
+string sub = input.Substring(5, 10);
+```
+✅
+```csharp
+ReadOnlySpan<char> sub = input.AsSpan(5, 10);
+```
+**Impact: Eliminates per-slice allocations; 2-4x faster via vectorization.**
+
+### Use ArrayPool\<T\> for Temporary Buffers
+🔴 **DO** | .NET Core+
+
+❌
+```csharp
+byte[] buf = new byte[4096];
+```
+✅
+```csharp
+byte[] buf = ArrayPool<byte>.Shared.Rent(4096);
+Process(buf);
+ArrayPool<byte>.Shared.Return(buf);
+```
+**Impact: Dramatically reduces GC pressure for buffer-heavy workloads.**
+
+### Avoid stackalloc in Loops
+🔴 **AVOID** | .NET 5+
+
+❌
+```csharp
+for (int i = 0; i < 10_000; i++)
+    Span<byte> buf = stackalloc byte[1024];
+```
+✅
+```csharp
+Span<byte> buf = stackalloc byte[1024];
+for (int i = 0; i < 10_000; i++) { Process(buf); }
+```
+**Impact: StackOverflowException — unrecoverable, no catch possible.**
+
+### Avoid Boxing Value Types
+🔴 **AVOID** | .NET 6+
+
+❌
+```csharp
+string s = string.Format("{0}.{1}", major, minor);
+```
+✅
+```csharp
+string s = $"{major}.{minor}";
+```
+**Impact: When replacing `string.Format` with C# 10+ interpolation, typical improvements are ~40% faster with significantly less allocation. Actual gains vary by call site.**
+
+## Strings
+
+### Use StringComparison.Ordinal for Non-Linguistic Comparisons
+🔴 **DO** | .NET Core+
+
+❌
+```csharp
+bool found = text.IndexOf("Content-Type") >= 0;
+```
+✅
+```csharp
+bool found = text.Contains("Content-Type", StringComparison.Ordinal);
+```
+**Impact: 2-3x faster; OrdinalIgnoreCase hash codes ~3.3x faster.**
+
+### Use AsSpan Instead of Substring
+🔴 **DO** | .NET Core 2.1+
+
+❌
+```csharp
+int val = int.Parse(str.Substring(5, 3));
+```
+✅
+```csharp
+int val = int.Parse(str.AsSpan(5, 3));
+```
+**Impact: Eliminates one string allocation per parse operation.**
+
+## Regular Expressions
+
+### Use Source-Generated Regex [GeneratedRegex]
+🔴 **ALWAYS** use `[GeneratedRegex]` for all static regex patterns | .NET 7+
+
+❌
+```csharp
+private static readonly Regex s_re =
+    new(@"\w+@\w+\.\w+", RegexOptions.Compiled);
+```
+✅
+```csharp
+[GeneratedRegex(@"\w+@\w+\.\w+")]
+private static partial Regex EmailRegex();
+```
+**Impact: Always beneficial or neutral for static patterns — near-zero startup, better throughput, and required for AOT/trimming scenarios.**
+
+### Avoid Nested Quantifiers (Catastrophic Backtracking)
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+var r = new Regex(@"^(\w+)+$");
+```
+✅
+```csharp
+var r = new Regex(@"^\w+$", RegexOptions.NonBacktracking);
+```
+**Impact: Can hang process indefinitely on crafted input.**
+
+### Use TryGetValue Instead of ContainsKey + Indexer
+🔴 **DO** | .NET Core+
+
+❌
+```csharp
+if (dict.ContainsKey(key))
+    Use(dict[key]);
+```
+✅
+```csharp
+if (dict.TryGetValue(key, out var value))
+    Use(value);
+```
+**Impact: ~2x faster (50% reduction in lookup time).**
+
+### Avoid LINQ in Hot Paths
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+bool found = items.Any(x => x.Name == target);
+```
+✅
+```csharp
+bool found = false;
+foreach (var item in items)
+    if (item.Name == target) { found = true; break; }
+```
+**Impact: Eliminates 1-3 allocations per call; measurable in tight loops.**
+
+### Don't Iterate IEnumerable Multiple Times
+🔴 **AVOID** | .NET Core+
+
+❌
+```csharp
+foreach (Type t in types) { Validate(t); }
+_types = types.ToArray();
+```
+✅
+```csharp
+Type[] arr = types.ToArray();
+foreach (Type t in arr) { Validate(t); }
+_types = arr;
+```
+**Impact: Halves enumeration cost; prevents bugs from re-executing deferred queries.**
+
+## JSON Serialization
+
+### Use System.Text.Json Source Generator
+🔴 **DO** | .NET 6+
+
+❌
+```csharp
+string json = JsonSerializer.Serialize(post);
+```
+✅
+```csharp
+[JsonSerializable(typeof(BlogPost))]
+internal partial class AppJsonCtx : JsonSerializerContext { }
+string json = JsonSerializer.Serialize(post, AppJsonCtx.Default.BlogPost);
+```
+**Impact: 37-44% faster; enables trimming and Native AOT.**
+
+### Cache JsonSerializerOptions
+🔴 **DO** | .NET 5+
+
+❌
+```csharp
+JsonSerializer.Serialize(obj, new JsonSerializerOptions());
+```
+✅
+```csharp
+private static readonly JsonSerializerOptions s_opts = new();
+JsonSerializer.Serialize(obj, s_opts);
+```
+**Impact: Up to 592x slower without caching (.NET 6); always cache or use defaults.**
+
+## Networking
+
+### Reuse HttpClient Instances
+🔴 **DO** | .NET Core 2.1+
+
+❌
+```csharp
+using var client = new HttpClient();
+await client.GetStringAsync(url);
+```
+✅
+```csharp
+private static readonly HttpClient s_http = new(new SocketsHttpHandler
+{ PooledConnectionLifetime = TimeSpan.FromMinutes(5) });
+await s_http.GetStringAsync(url);
+```
+**Impact: Prevents socket exhaustion; 6-12x faster concurrent HTTPS.**
+
+## General
+
+### Use SearchValues\<T\> for Repeated Set Searches
+🔴 **DO** | .NET 8+
+
+❌
+```csharp
+int pos = text.IndexOfAny("ABCDEF".ToCharArray());
+```
+✅
+```csharp
+private static readonly SearchValues<char> s_hex = SearchValues.Create("ABCDEF");
+int pos = text.AsSpan().IndexOfAny(s_hex);
+```
+**Impact: 2-10x faster for chars; 10-30x faster for multi-string (.NET 9+).**
+
+## Detection
+
+Scan recipes for critical anti-patterns. Run these and report exact counts of issues found in each case.
+
+```bash
+# .IndexOf(string) without StringComparison (culture-aware, 2-3x slower)
+grep -rn --include='*.cs' -E '\.IndexOf\("[^"]+"\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# .Substring( calls (allocates new string — consider AsSpan)
+grep -rn --include='*.cs' '\.Substring(' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# .StartsWith/.EndsWith without StringComparison (culture-aware, 2-3x slower)
+grep -rn --include='*.cs' -E '\.(StartsWith|EndsWith)\("[^"]+"\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+
+# .Contains(string) without StringComparison — NOTE: will also match collection .Contains() calls; filter to string receivers
+grep -rn --include='*.cs' -E '\.Contains\("[^"]+"\)' --exclude-dir=bin --exclude-dir=obj . | wc -l
+```