@cratis/pi 7.102.0 → 7.103.0

package/package/corpus/skills/microbenchmarking/references/diagnosers-and-exporters.md

@@ -0,0 +1,150 @@
+# Measurement and diagnostics
+
+## Contents
+
+- Diagnosers
+- Statistical output
+- Outlier handling
+- Export formats
+
+BenchmarkDotNet measures wall-clock time by default. This reference covers how to collect additional data (allocations, disassembly, hardware counters), customize statistical output, and export results.
+
+## Diagnosers
+
+Diagnosers add columns or produce artifacts beyond basic timing. They are enabled via class-level attributes or CLI flags.
+
+### MemoryDiagnoser
+
+| Surface | Usage |
+|---------|-------|
+| Attribute | `[MemoryDiagnoser]` or `[MemoryDiagnoser(displayGenColumns: false)]` |
+| Config | `.AddDiagnoser(MemoryDiagnoser.Default)` |
+| CLI | `--memory` |
+
+Tracks managed heap allocations and GC collections per operation.
+
+Adds columns: `Gen0`, `Gen1`, `Gen2` (GC collections per 1000 operations — a value of `1.0000` means one collection per 1000 operations), `Allocated` (bytes per operation).
+
+Set `displayGenColumns: false` if only total allocated bytes matter.
+
+### DisassemblyDiagnoser
+
+| Surface | Usage |
+|---------|-------|
+| Attribute | `[DisassemblyDiagnoser(maxDepth: 2)]` |
+| Config | `.AddDiagnoser(new DisassemblyDiagnoser(new DisassemblyDiagnoserConfig(maxDepth: 2, printSource: true)))` |
+| CLI | `--disasm`, `--disasmDepth N`, `--disasmDiff`, `--disasmFilter "Method*"` |
+
+Captures the JIT-compiled assembly code for the benchmark method.
+
+Produces: a per-benchmark disassembly report (exported as GitHub Markdown and/or HTML).
+
+Config options (`DisassemblyDiagnoserConfig`):
+- `maxDepth` (default 1) — how many levels of called methods to include in the disassembly.
+- `syntax` — `DisassemblySyntax.Masm` (default), `Intel`, or `Att`
+- `printSource` (default false) — include C#/F#/VB source alongside assembly
+- `exportDiff` (default false) — when comparing multiple jobs, export a diff view
+- `exportCombinedDisassemblyReport` (default false) — all benchmarks in a single HTML report for side-by-side comparison
+
+When using `printSource: true`, ensure the benchmark project emits PDB files so BDN can map assembly instructions to source lines:
+
+```xml
+<DebugType>pdbonly</DebugType>
+<DebugSymbols>true</DebugSymbols>
+```
+
+### ThreadingDiagnoser
+
+`[ThreadingDiagnoser]` (CLI: `--threading`, Config: `.AddDiagnoser(ThreadingDiagnoser.Default)`) — adds `Completed Work Items` and `Lock Contentions` columns.
+
+### EventPipeProfiler
+
+| Surface | Usage |
+|---------|-------|
+| Attribute | `[EventPipeProfiler(EventPipeProfile.CpuSampling)]` |
+| Config | `.AddDiagnoser(new EventPipeProfiler(EventPipeProfile.CpuSampling))` |
+| CLI | `--profiler EP` |
+
+Collects CPU sampling profiles using .NET's EventPipe infrastructure. Cross-platform.
+
+Profiles available: `CpuSampling`, `GcVerbose`, `GcCollect`, `Jit`.
+
+Produces: `.nettrace` and `.speedscope.json` files. By default (attribute/config), runs an extra benchmark iteration dedicated to profiling so timing results are unaffected.
+
+**CLI note:** `--profiler EP` uses `CpuSampling` with `performExtraBenchmarksRun: false` — profiling is attached to normal measurement runs (no extra iteration, results include profiler overhead, no way to select a different profile). Use the attribute or config API for full control.
+
+### HardwareCounters (Windows only, requires elevation)
+
+| Surface | Usage |
+|---------|-------|
+| Attribute | `[HardwareCounters(HardwareCounter.CacheMisses, HardwareCounter.BranchMispredictions)]` |
+| Config | `.AddHardwareCounters(HardwareCounter.CacheMisses, HardwareCounter.BranchMispredictions)` |
+| CLI | `--counters CacheMisses+BranchMispredictions` |
+
+Collects CPU hardware performance counters via ETW.
+
+Available counters include: `TotalCycles`, `InstructionRetired`, `CacheMisses`, `BranchMispredictions`, `BranchInstructions`, `LlcMisses`, `LlcReference`.
+
+Requires: Windows, elevated (admin) process, and ETW support. Not available on all hardware.
+
+## Statistical output
+
+### Default columns
+
+| Column | Meaning |
+|--------|---------|
+| `Mean` | Average per-operation time across all measured iterations |
+| `Error` | Half-width of the 99.9% confidence interval — if large relative to Mean, results are noisy |
+| `StdDev` | Standard deviation of measurements (hidden when negligible) |
+| `Median` | Median per-operation time (auto-shown when data is skewed or median diverges from mean) |
+| `P95` | 95th percentile (auto-shown when extreme outliers are present) |
+| `Ratio` | Performance relative to the baseline (current / baseline) — only shown when a baseline is marked. A value of `0.85` means ~15% faster. See [comparison-strategies.md](comparison-strategies.md) for how this is calculated |
+| `RatioSD` | Standard deviation of the ratio distribution |
+
+### Adding columns
+
+Additional statistics can be added via attributes on the benchmark class:
+
+| Attribute | Column added |
+|-----------|-------------|
+| `[MedianColumn]` | Median (P50) |
+| `[MinColumn]`, `[MaxColumn]` | Minimum, Maximum |
+| `[Q1Column]`, `[Q3Column]` | First quartile (P25), Third quartile (P75) |
+| `[AllStatisticsColumn]` | Mean, StdErr, StdDev, Ops/s, Min, Q1, Median, Q3, Max |
+| `[RankColumn]` | Rank (1, 2, 3...) |
+| `[SkewnessColumn]`, `[KurtosisColumn]` | Distribution shape metrics |
+| `[OperationsPerSecond]` | Throughput (ops/sec) |
+
+Percentile columns are available via code: `StatisticColumn.P50`, `StatisticColumn.P85`, `StatisticColumn.P95`, etc.
+
+### Hiding columns
+
+Use `[HideColumns]` to remove unwanted columns from the output:
+
+```csharp
+[HideColumns("Error", "StdDev", "RatioSD")]
+public class MyBenchmark { ... }
+```
+
+## Outlier handling
+
+| Surface | Usage |
+|---------|-------|
+| Attribute | `[Outliers(OutlierMode.DontRemove)]` |
+| Config | `.WithOutlierMode(OutlierMode.DontRemove)` |
+| CLI | `--outliers DontRemove` |
+
+By default, BDN removes upper outliers (unusually slow iterations, typically caused by GC or OS interference). Available modes: `DontRemove`, `RemoveUpper` (default), `RemoveLower`, `RemoveAll`.
+
+## Export formats
+
+BDN exports results in multiple formats. By default it produces Markdown and CSV in the `BenchmarkDotNet.Artifacts/results/` directory.
+
+| Format | Default | Config | CLI flag |
+|--------|---------|--------|----------|
+| JSON (full, indented) | no | `.AddExporter(JsonExporter.Full)` | `--exporters fulljson` |
+| JSON (compressed) | no | `.AddExporter(JsonExporter.Default)` | `--exporters json` |
+| CSV | yes | `.AddExporter(CsvExporter.Default)` | `--exporters csv` |
+| GitHub Markdown | yes | `.AddExporter(MarkdownExporter.GitHub)` | `--exporters github` |
+
+Use `JsonExporter.Full` for individual measurements (needed for programmatic comparison).

package/package/corpus/skills/microbenchmarking/references/project-setup-and-running.md

@@ -0,0 +1,189 @@
+# Running benchmarks
+
+## Contents
+
+- Entry points: BenchmarkSwitcher vs BenchmarkRunner
+- Config objects
+- Creating a new benchmark project
+- Build and run strategy
+- Artifacts directory
+- Useful CLI flags for agents
+- Dry run validation
+
+This reference covers how to build, run, and read BenchmarkDotNet results. It also covers common CLI flags for controlling output and debugging.
+
+## Entry points: BenchmarkSwitcher vs BenchmarkRunner
+
+BenchmarkDotNet programs use one of two entry points. This determines whether CLI arguments work:
+
+**BenchmarkSwitcher** — passes `args` to BDN, CLI flags work:
+```csharp
+BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args);
+BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args, config); // with config
+```
+
+**BenchmarkRunner** — only forwards args if explicitly passed:
+```csharp
+BenchmarkRunner.Run<MyBenchmark>();                     // CLI flags IGNORED
+BenchmarkRunner.Run<MyBenchmark>(args: args);            // CLI flags work
+BenchmarkRunner.Run<MyBenchmark>(config);                // config only, no CLI
+BenchmarkRunner.Run<MyBenchmark>(config, args);          // both config and CLI
+```
+
+Before passing CLI flags like `--filter` or `--job`, check which entry point the program uses. If it uses `BenchmarkRunner.Run<T>()` without args, CLI flags will be silently ignored — configuration must be done through attributes and `ManualConfig` instead.
+
+**Critical**: when `BenchmarkSwitcher` is used, it prompts the user interactively to select which benchmarks to run unless `--filter` is provided. For AI agents, always pass `--filter` to avoid hanging on an interactive prompt. `--filter "*"` matches everything and is the standard way to run all benchmarks non-interactively.
+
+## Config objects
+
+Configs can be built in three ways:
+
+**Modify the default config** — starts with all default loggers, exporters, and columns:
+```csharp
+var config = DefaultConfig.Instance
+    .AddJob(Job.Default.WithRuntime(CoreRuntime.Core90))
+    .AddDiagnoser(MemoryDiagnoser.Default);
+```
+
+**Subclass ManualConfig** — useful when config is complex or reused across classes:
+```csharp
+public class MyConfig : ManualConfig
+{
+    public MyConfig()
+    {
+        AddJob(Job.Default.WithRuntime(CoreRuntime.Core80));
+        AddJob(Job.Default.WithRuntime(CoreRuntime.Core90).AsBaseline());
+        AddDiagnoser(MemoryDiagnoser.Default);
+    }
+}
+```
+
+**Start from empty** — `ManualConfig.CreateEmpty()` removes all defaults (no loggers, no exporters, no columns). Use `ManualConfig.CreateMinimumViable()` instead to start with the default columns and console logger.
+
+Configs can be applied in several ways:
+
+| Method | Scope |
+|--------|-------|
+| `BenchmarkRunner.Run<T>(config)` | All benchmarks in the run |
+| `BenchmarkSwitcher...Run(args, config)` | All benchmarks in the run |
+| `[Config(typeof(MyConfig))]` on class or assembly | That class, or all classes in the assembly |
+
+## Creating a new benchmark project
+
+If there is no existing benchmark project to add to, create a new console project with `dotnet new console` and add the BenchmarkDotNet package. Choose a temporary or permanent location based on the scope of the work.
+
+Use `dotnet add package BenchmarkDotNet` without specifying a version — `dotnet` resolves the latest compatible version automatically. Pinning to a specific version risks missing support for newer runtimes and CLI features.
+
+**Multi-runtime targeting**: to compare across runtimes (e.g., `--runtimes net8.0 net9.0`), the `.csproj` must use the plural `<TargetFrameworks>` property listing all targets:
+
+```xml
+<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
+```
+
+If the project uses the singular `<TargetFramework>` with only one TFM, multi-runtime runs will fail at build time.
+
+Then replace `Program.cs` with:
+```csharp
+using BenchmarkDotNet.Running;
+
+BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args);
+```
+
+Adjust the `ProjectReference` path to match the project under test. If benchmarking code that isn't in a separate project, skip `dotnet add reference` and put the code under test directly in the benchmark project.
+
+## Build and run strategy
+
+BenchmarkDotNet console output is extremely verbose — hundreds of lines per case showing pilot, warmup, and actual iteration details. Redirect all output to a file to avoid consuming context on verbose iteration output.
+
+**Recommended approach**: build first, then run with output redirected to a file. Always pass `--noOverwrite` so each run writes results to a timestamped subdirectory instead of `BenchmarkDotNet.Artifacts/results/` — without it, each run overwrites the previous results, making it easy to get confused about which run the results are for.
+
+Each benchmark method can take several minutes. Rather than running all benchmarks at once, use `--filter` to run a subset at a time (e.g. one or two methods per invocation), read the results, then run the next subset. This keeps each invocation short — avoiding session or terminal timeouts — and lets you verify results incrementally.
+
+```
+dotnet build -c Release
+dotnet run -c Release --no-build -- --filter "*MethodName" --noOverwrite > benchmark.log 2>&1
+```
+
+After each run, read the Markdown report (`*-report-github.md`) for the summary table. Only read `benchmark.log` if you need to investigate errors or unexpected results.
+
+## Artifacts directory
+
+By default, BDN writes to `BenchmarkDotNet.Artifacts/` relative to the working directory. Override with:
+
+```
+dotnet run -c Release --no-build -- --artifacts ./my-results
+```
+
+The artifacts directory contains:
+```
+BenchmarkDotNet.Artifacts/
+├── MyBenchmark-20240101-120000.log    # full console log
+└── results/
+    ├── MyBenchmark-report-github.md   # markdown summary table
+    └── MyBenchmark-report.csv         # CSV data
+```
+
+Use `--noOverwrite` to prevent overwriting previous results (writes to `BenchmarkDotNet.Artifacts/<timestamp>/` instead of `BenchmarkDotNet.Artifacts/results/`). Use `--artifacts` with different paths when comparing results from separate runs.
+
+## Useful CLI flags for agents
+
+### Filtering and discovery
+
+| Flag | Purpose |
+|------|---------|
+| `--filter "*"` | Run all benchmarks (avoids interactive prompt from BenchmarkSwitcher) |
+| `--filter "*.MethodName"` | Run specific benchmark methods |
+| `--list flat` | List available benchmark names without running them |
+| `--list tree` | List benchmarks in a tree hierarchy |
+| `--allCategories <name>` | Run only benchmarks matching all specified categories |
+| `--anyCategories <name>` | Run benchmarks matching any specified category |
+
+Tag benchmarks with `[BenchmarkCategory("name")]` (on methods, classes, or assemblies) to enable category-based filtering.
+
+**How `--filter` works**: BDN matches each pattern against two forms of the benchmark name:
+- **Short form**: `Namespace.ClassName.MethodName` (no parameters)
+- **Full form**: `Namespace.ClassName.MethodName(param: value, ...)` (includes parameters when present)
+
+Patterns use glob wildcards (`*` = any characters, `?` = single character), are **case-insensitive**, and must match the **entire** name (anchored). Multiple `--filter` values are OR'd — a case runs if it matches any pattern.
+
+| Goal | Pattern |
+|------|---------|
+| Run all benchmarks | `--filter "*"` |
+| Run one method by name | `--filter "*MyMethod"` |
+| Run all methods in a class | `--filter "*MyClass*"` |
+| Run a specific class.method | `--filter "MyNamespace.MyClass.MyMethod"` |
+| Same, using wildcard for namespace | `--filter "*MyClass.MyMethod"` |
+| Run two specific methods | `--filter "*MethodA" --filter "*MethodB"` |
+| Run methods matching a substring | `--filter "*Sort*"` |
+
+**Tip**: because patterns are anchored, `--filter "MyMethod"` does **not** match `MyNamespace.MyClass.MyMethod` — always use a leading `*` unless matching the short form exactly. Use `--list flat` to see the exact names BDN uses for filtering.
+
+**Category-based filtering**: tag benchmarks with `[BenchmarkCategory("name")]` on methods, classes, or assemblies to enable category filtering. Categories are inherited — a method tagged `"Parsing"` on a class tagged `"Strings"` has both categories.
+
+| Flag | Behavior |
+|------|----------|
+| `--anyCategories Parsing Sorting` | Run benchmarks that have **at least one** of the listed categories |
+| `--allCategories Strings Parsing` | Run benchmarks that have **all** of the listed categories |
+
+When `--filter` and `--allCategories`/`--anyCategories` are used together, a benchmark must satisfy **both** — the glob filter AND the category filter are AND'd together.
+
+### Output control
+
+| Flag | Purpose |
+|------|---------|
+| `--artifacts ./path` | Change where results are written |
+| `--noOverwrite` | Don't overwrite previous result files |
+| `--exporters json` | Add JSON export (useful for programmatic comparison) |
+| `--join` | Combine results from multiple benchmark classes into a single table |
+| `--hide "Error" "StdDev"` | Hide specific columns from the results table |
+| `--keepFiles` | Keep the generated benchmark project files — useful for debugging build failures |
+
+## Dry run validation
+
+Always run `--job Dry` first to catch compilation and runtime errors before committing to a full run:
+
+```
+dotnet run -c Release --no-build -- --filter "*" --job Dry --noOverwrite
+```
+
+A dry run executes each case once (<1 second per case) without meaningful measurement. It validates that setup methods work, parameters are valid, and the benchmark compiles and executes. Only after dry validation passes should you run with default or other job presets.

package/package/corpus/skills/microbenchmarking/references/writing-benchmarks.md

@@ -0,0 +1,310 @@
+# Benchmark authoring techniques
+
+## Contents
+
+- Dead code elimination
+- Setup and cleanup
+- OperationsPerInvoke
+- Avoiding loops
+- No side effects
+- Async benchmarks
+- Deferred execution
+- Constant folding
+- Randomness and reproducibility
+- Benchmark class constraints
+- Parameterization summary
+
+This reference covers BenchmarkDotNet features and practices for writing correct benchmark methods. Incorrect benchmarks silently produce misleading results — the techniques here prevent common measurement errors.
+
+## Dead code elimination
+
+The JIT compiler can eliminate code whose result is never used. If a benchmark method returns `void` and doesn't store its result anywhere observable, the JIT may partially or fully optimize away the computation.
+
+**Returning a value from the benchmark method prevents this.** When the method has a non-void return type, the JIT cannot prove the result is unused (the call site in BDN's generated harness is opaque to the JIT), so it must preserve the computation:
+
+```csharp
+// Correct — non-void return prevents DCE
+[Benchmark]
+public int Parse() => int.Parse("12345");
+
+// Wrong — void return, JIT may eliminate the call
+[Benchmark]
+public void Parse() => int.Parse("12345");
+```
+
+For benchmarks that must return `void` (e.g., methods with side effects like `Array.Sort`), DCE is not a concern because the operation itself has observable effects.
+
+For iterating deferred sequences where returning the sequence object doesn't force enumeration, use the `Consumer` class explicitly — see [Deferred execution](#deferred-execution).
+
+## Setup and cleanup
+
+### GlobalSetup / GlobalCleanup
+
+A method marked `[GlobalSetup]` runs once per benchmark case, before all iterations of that case. Use it to allocate buffers, load data, and initialize state that the benchmark reads but does not mutate.
+
+```csharp
+private int[] _array;
+
+[GlobalSetup]
+public void Setup() => _array = Enumerable.Range(0, 1000).ToArray();
+
+[Benchmark]
+public int Sum() => _array.Sum();
+```
+
+Initialization logic inside the benchmark method itself is measured — this is almost never what you want.
+
+When a class has multiple benchmarks needing different setup, use the `Target` or `Targets` property:
+
+```csharp
+[GlobalSetup(Target = nameof(BenchmarkA))]
+public void SetupA() { ... }
+
+[GlobalSetup(Targets = new[] { nameof(BenchmarkB), nameof(BenchmarkC) })]
+public void SetupBC() { ... }
+```
+
+`[GlobalCleanup]` runs once after all iterations. Use it to dispose resources (files, connections) created during setup.
+
+**Note**: when `[MemoryRandomization]` is enabled, BDN re-runs `[GlobalCleanup]` and `[GlobalSetup]` after every iteration (overriding the normal once-only behavior). See [references/bdn-internals-and-tuning.md](bdn-internals-and-tuning.md) for details.
+
+### IterationSetup / IterationCleanup
+
+A method marked `[IterationSetup]` runs before every iteration. Use it only when the benchmark mutates state that must be reset — for example, sorting an array in-place.
+
+**Critical constraint**: when `[IterationSetup]` or `[IterationCleanup]` is used, BDN defaults to `InvocationCount=1` and `UnrollFactor=1` (unless explicitly overridden). This means the entire iteration is a single invocation, so the operation should be long enough (generally hundreds of milliseconds or more) for a single-invocation measurement to be reliable — with only one invocation, OS scheduling jitter and timer resolution become a significant fraction of the measured time.
+
+```csharp
+[Params(10_000_000)] // large enough for single-invocation measurement
+public int Size { get; set; }
+
+private int[] _data, _scratch;
+
+[GlobalSetup]
+public void Setup() => _data = Enumerable.Range(0, Size).Reverse().ToArray();
+
+[IterationSetup]
+public void ResetArray() => Array.Copy(_data, _scratch = new int[Size], Size);
+
+[Benchmark]
+public void Sort() => Array.Sort(_scratch);
+```
+
+**If `[GlobalSetup]` is sufficient, do not use `[IterationSetup]`.** It adds overhead and constrains the measurement.
+
+## OperationsPerInvoke
+
+When part of the benchmark setup cannot be moved to `[GlobalSetup]` — typically because it involves a stack-only type like `Span<T>` — use `OperationsPerInvoke` to amortize the setup cost by performing multiple logical operations per invocation.
+
+```csharp
+private byte[] _array = new byte[18];
+
+[Benchmark(OperationsPerInvoke = 16)]
+public Span<byte> Slice()
+{
+    Span<byte> span = new Span<byte>(_array); // setup: can't go in GlobalSetup (stack-only)
+
+    // 16 operations, unrolled without a loop
+    span = span.Slice(1); span = span.Slice(1); span = span.Slice(1); span = span.Slice(1);
+    span = span.Slice(1); span = span.Slice(1); span = span.Slice(1); span = span.Slice(1);
+    span = span.Slice(1); span = span.Slice(1); span = span.Slice(1); span = span.Slice(1);
+    span = span.Slice(1); span = span.Slice(1); span = span.Slice(1); span = span.Slice(1);
+
+    return span;
+}
+```
+
+BDN divides the measured time by `OperationsPerInvoke`, so the reported result reflects a single `Slice` operation with the `Span` creation cost amortized. The operations are manually unrolled (not in a loop) to avoid loop overhead affecting the measurement.
+
+## Avoiding loops
+
+BDN determines how many times to invoke the benchmark method per iteration automatically (the pilot stage). Adding a manual loop inside the benchmark is unnecessary and harmful:
+
+```csharp
+// Wrong — manual loop adds loop overhead and hides per-operation variance
+[Benchmark]
+public int ParseLoop()
+{
+    int result = 0;
+    for (int i = 0; i < 1000; i++)
+        result += int.Parse("12345");
+    return result;
+}
+
+// Correct — BDN handles invocation count
+[Benchmark]
+public int Parse() => int.Parse("12345");
+```
+
+The exception is `OperationsPerInvoke` — when per-invocation setup cannot be avoided, repeating the operation inside the method and declaring the count lets BDN divide the result correctly.
+
+## No side effects
+
+Benchmarks should be idempotent — running the method N times should produce the same performance characteristics as running it once. A benchmark that grows a list on every invocation violates this:
+
+```csharp
+// Wrong — list grows with every invocation, later calls are slower
+List<int> _numbers = new();
+
+[Benchmark]
+public void Add() => _numbers.Add(12345);
+```
+
+If the operation inherently mutates state (e.g., `Array.Sort`), use `[IterationSetup]` to reset state between iterations, with input large enough for reliable single-invocation measurement.
+
+## Async benchmarks
+
+BDN natively supports benchmark methods that return `Task`, `Task<T>`, `ValueTask`, or `ValueTask<T>`. BDN awaits the result automatically — there is no special attribute or configuration needed:
+
+```csharp
+[Benchmark]
+public async Task<int> ReadAsync()
+{
+    using var stream = new FileStream(_path, FileMode.Open, FileAccess.Read, FileShare.Read, 4096, useAsync: true);
+    var buffer = new byte[4096];
+    return await stream.ReadAsync(buffer);
+}
+```
+
+**Async setup/cleanup**: `[GlobalSetup]` and `[GlobalCleanup]` methods can also return `Task` or `ValueTask` — BDN awaits them automatically. `[IterationSetup]` and `[IterationCleanup]` do **not** support async return types; they must be synchronous.
+
+**When NOT to use async**: if the operation being benchmarked is synchronous, do not wrap it in `async`/`await`. The async state machine adds overhead that would be included in the measurement:
+
+```csharp
+// Wrong — adds async state machine overhead to a synchronous operation
+[Benchmark]
+public async Task<int> ParseAsync() => await Task.FromResult(int.Parse("12345"));
+
+// Correct — benchmark the synchronous method directly
+[Benchmark]
+public int Parse() => int.Parse("12345");
+```
+
+## Deferred execution
+
+Returning `IEnumerable<T>`, `IQueryable<T>`, or `Lazy<T>` from a benchmark measures only the creation of the deferred sequence — not its execution. This is almost always a bug:
+
+```csharp
+// Wrong — measures only the creation of the LINQ query object, not its execution
+[Benchmark]
+public IEnumerable<int> WhereQuery() => _numbers.Where(n => n > 50);
+
+// Correct — materialize the result so the query actually executes
+[Benchmark]
+public List<int> WhereQuery() => _numbers.Where(n => n > 50).ToList();
+```
+
+BDN includes a `DeferredExecutionValidator` that detects this mistake and raises a validation error, preventing the benchmark from running. To fix it, either materialize the result (`.ToList()`, `.ToArray()`) or consume it manually using the `.Consume()` extension method:
+
+```csharp
+private Consumer _consumer = new();
+
+[Benchmark]
+public void WhereQuery() => _numbers.Where(n => n > 50).Consume(_consumer);
+```
+
+## Constant folding
+
+The JIT can evaluate expressions at compile time when all inputs are constants or literals. If a benchmark operates on constant inputs, the JIT may fold the computation into a precomputed result, and the benchmark measures nothing:
+
+```csharp
+// Wrong — JIT can compute Math.Sqrt(144.0) at compile time
+[Benchmark]
+public double Sqrt() => Math.Sqrt(144.0);
+
+// Correct — field value is not a compile-time constant
+private double _value = 144.0;
+
+[Benchmark]
+public double Sqrt() => Math.Sqrt(_value);
+```
+
+Store inputs in fields, `[Params]`, or `[Arguments]` — never as literals or `const` values in the benchmark method.
+
+## Randomness and reproducibility
+
+When benchmarks use generated input data, use a fixed seed so results are comparable across runs:
+
+```csharp
+[GlobalSetup]
+public void Setup()
+{
+    var rng = new Random(42); // fixed seed
+    _data = new byte[Size];
+    rng.NextBytes(_data);
+}
+```
+
+## Benchmark class constraints
+
+BDN generates source code for a derived type from the benchmark class, which is compiled as part of its generated project. This imposes constraints:
+- The class must be `public`
+- The class must not be `sealed`, `static`, or `abstract`
+- The class must be a `class`, not a `struct` or `ref struct`
+- Benchmark methods must be `public` and instance (not `static`)
+
+## Parameterization summary
+
+| Feature | Target | Use when |
+|---------|--------|----------|
+| `[Params]` | Field/Property | Values needed in setup; applies to all benchmarks in the class |
+| `[ParamsSource]` | Field/Property | Dynamic or complex values needed in setup |
+| `[ParamsAllValues]` | Field/Property | Enum or bool — test every possible value |
+| `[Arguments]` | Method | Inline values for a specific benchmark method |
+| `[ArgumentsSource]` | Method | Dynamic or complex values for a specific benchmark method |
+| `[GenericTypeArguments]` | Class | Vary type parameters (e.g., value type vs reference type) |
+
+`[Params]` applies to all benchmarks in the class. If different benchmarks need different parameter ranges, split them into separate classes.
+
+`[Arguments]` and `[ArgumentsSource]` are method-specific and their initialization time is excluded from the measurement. `[ArgumentsSource]` methods return `IEnumerable<T>` for single-parameter benchmarks, or `IEnumerable<object[]>` for multi-parameter benchmarks (each array is one set of arguments). `[ParamsSource]` methods return `IEnumerable<T>` (each element is a single value assigned to the field/property).
+
+```csharp
+// Single-parameter: IEnumerable<T>
+[Benchmark]
+[ArgumentsSource(nameof(Inputs))]
+public int Parse(string text) => int.Parse(text);
+
+public IEnumerable<string> Inputs()
+{
+    yield return "12345";
+    yield return "999999999";
+    yield return "-42";
+}
+
+// Multi-parameter: IEnumerable<object[]>
+[Benchmark]
+[ArgumentsSource(nameof(Inputs))]
+public bool TryParse(string text, NumberStyles style) => int.TryParse(text, style, null, out _);
+
+public IEnumerable<object[]> Inputs()
+{
+    yield return new object[] { "12345", NumberStyles.Integer };
+    yield return new object[] { "0xFF", NumberStyles.HexNumber };
+}
+```
+
+`[ParamsSource]` works the same way but targets a field/property and applies to all benchmarks in the class:
+
+```csharp
+[ParamsSource(nameof(Sizes))]
+public int N;
+
+public IEnumerable<int> Sizes() => new[] { 100, 1_000, 10_000 };
+```
+
+`[GenericTypeArguments]` varies type parameters on a generic benchmark class. Each attribute creates a separate closed generic type that BDN runs independently:
+
+```csharp
+[GenericTypeArguments(typeof(int))]
+[GenericTypeArguments(typeof(string))]
+public class CollectionBenchmark<T>
+{
+    private List<T> _list;
+
+    [GlobalSetup]
+    public void Setup() => _list = new List<T>(Enumerable.Repeat(default(T)!, 1000));
+
+    [Benchmark]
+    public bool Contains() => _list.Contains(default!);
+}
+```

package/package/corpus/skills/msbuild/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.