Skip to content

ByteTerrace/Puck / .claude/skills/dotnet-performance

dotnet-performance

Verified

Tunes Puck .NET 11 performance: allocation, gen0 pauses, layout, false sharing, LINQ, SIMD, Vector<T>, async, JIT tiering, first-call latency, AllocationWindow, puck bench, AOT. Numerics: maths-usage.

FileKindSize
SKILL.mdskill md20.9 KB
evals/n01-linq-to-loop/graders/allocation-window-meter.mdmarkdown667 B
evals/n01-linq-to-loop/graders/checks-obsolete-folklore.mdmarkdown832 B
evals/n01-linq-to-loop/graders/counts-are-the-verdict.mdmarkdown502 B
evals/n01-linq-to-loop/graders/demonstrated-hot-path.mdmarkdown562 B
evals/n01-linq-to-loop/graders/judged-by-dividends.mdmarkdown664 B
evals/n01-linq-to-loop/graders/preserves-semantics.mdmarkdown819 B
evals/n01-linq-to-loop/graders/puck-bench-harness.mdmarkdown69 B
evals/n01-linq-to-loop/graders/skill-fired.mdmarkdown36 B
evals/n01-linq-to-loop/graders/timing-is-interleaved-ab.mdmarkdown538 B
evals/n01-linq-to-loop/prompt.mdmarkdown383 B
evals/n02-vectorize-replayed-reduction/graders/bit-identity-before-measuring.mdmarkdown592 B
evals/n02-vectorize-replayed-reduction/graders/order-not-promised.mdmarkdown606 B
evals/n02-vectorize-replayed-reduction/graders/presentation-gets-a-fixed-order.mdmarkdown839 B
evals/n02-vectorize-replayed-reduction/graders/routes-to-maths-usage.mdmarkdown91 B
evals/n02-vectorize-replayed-reduction/graders/skill-fired.mdmarkdown36 B
evals/n02-vectorize-replayed-reduction/graders/throughput-is-not-enough.mdmarkdown764 B
evals/n02-vectorize-replayed-reduction/graders/value-moves-once.mdmarkdown943 B
evals/n02-vectorize-replayed-reduction/graders/width-varies.mdmarkdown669 B
evals/n02-vectorize-replayed-reduction/prompt.mdmarkdown439 B
evals/n03-aot-analysis-fails/graders/analysis-is-the-default.mdmarkdown839 B
evals/n03-aot-analysis-fails/graders/json-serializer-context.mdmarkdown78 B
evals/n03-aot-analysis-fails/graders/json-type-info-overloads.mdmarkdown69 B
evals/n03-aot-analysis-fails/graders/opt-out-only-for-a-structural-blocker.mdmarkdown719 B
evals/n03-aot-analysis-fails/graders/skill-fired.mdmarkdown36 B
evals/n03-aot-analysis-fails/prompt.mdmarkdown462 B
evals/n04-prove-zero-allocation/graders/allocation-window.mdmarkdown73 B
evals/n04-prove-zero-allocation/graders/gc-mode-matters.mdmarkdown712 B
evals/n04-prove-zero-allocation/graders/least-of-windows.mdmarkdown739 B
evals/n04-prove-zero-allocation/graders/no-law-gates-timing.mdmarkdown575 B
evals/n04-prove-zero-allocation/graders/skill-fired.mdmarkdown36 B
evals/n04-prove-zero-allocation/graders/warmed-body.mdmarkdown453 B
evals/n04-prove-zero-allocation/prompt.mdmarkdown268 B
evals/n05-first-call-latency/graders/checks-the-tier.mdmarkdown670 B
evals/n05-first-call-latency/graders/dispatcher-stays-tiered.mdmarkdown728 B
evals/n05-first-call-latency/graders/published-versus-il-build.mdmarkdown624 B
evals/n05-first-call-latency/graders/skill-fired.mdmarkdown36 B
evals/n05-first-call-latency/graders/tier-zero-until-promotion.mdmarkdown753 B
evals/n05-first-call-latency/prompt.mdmarkdown290 B
references/collections-and-linq.mdmarkdown32.7 KB
references/core-guidance.mdmarkdown33.6 KB
references/data-and-memory.mdmarkdown29.0 KB
references/io-network-json-crypto.mdmarkdown25.5 KB
references/jit-and-codegen.mdmarkdown41.8 KB
references/measured-changes.mdmarkdown12.4 KB
references/numerics-simd-threading.mdmarkdown30.0 KB
references/runtime-aot-reflection-diagnostics.mdmarkdown26.5 KB
references/strings-text-search.mdmarkdown28.5 KB
---
name: dotnet-performance
description: "Tunes Puck .NET 11 performance: allocation, gen0 pauses, layout, false sharing, LINQ, SIMD, Vector<T>, async, JIT tiering, first-call latency, AllocationWindow, puck bench, AOT. Numerics: maths-usage."
---

# .NET 11 performance

Judge a change by code, disassembly and load-independent counts (allocations,
operation counts, work counters). A wall-clock benchmark (`puck bench`) is
evidence beside those counts, never alone, and runs as interleaved A/B rounds
in the lead's quiet window through `puck measure run` or `puck lease quiet`.
The heavy lease alone does not make a timing window quiet. Keep runtime improvements
apart from workload-specific evidence.

`bench world` runs its collector against each frozen build's engine. Read a
source's `IWorkCounterSource.WorkKinds` rather than binding the CLI to individual
counter members: the measured source owns the kinds it exposes. Preserve the
root exception when a frozen build cannot run the harness; a type-initializer
wrapper hides the member or input that needs fixing.

## Route to the relevant evidence

| Area | Read |
|---|---|
| Cross-domain mental model, pattern changes, API shortlist, folklore | [references/core-guidance.md](references/core-guidance.md) |
| Landing a speed change: what keeps it, counters versus A/B timing, proving the changed path ran, PGO in the World, techniques and the hazards review finds | [references/measured-changes.md](references/measured-changes.md) |
| What the data costs: steady-state allocation, gen0 pauses and old-to-young references, LOH, layout and hot/cold splitting, struct copies, zero-fill and `stackalloc`, scans, bandwidth, false sharing, branches; measuring them here | [references/data-and-memory.md](references/data-and-memory.md) |
| JIT, codegen, allocation, inlining, bounds checks, ISA | [references/jit-and-codegen.md](references/jit-and-codegen.md) |
| Collections, LINQ, Frozen/Immutable, `CollectionsMarshal` | [references/collections-and-linq.md](references/collections-and-linq.md) |
| Strings, spans, search, regex, UTF-8, encoding | [references/strings-text-search.md](references/strings-text-search.md) |
| Numerics, SIMD, tensor APIs, randomness, threading | [references/numerics-simd-threading.md](references/numerics-simd-threading.md) |
| I/O, compression, networking, JSON, crypto | [references/io-network-json-crypto.md](references/io-network-json-crypto.md) |
| AOT, reflection, GC handles, diagnostics, DI, runtime, runtime async | [references/runtime-aot-reflection-diagnostics.md](references/runtime-aot-reflection-diagnostics.md) |

Read only the files relevant to the code under review. The references describe
.NET 11 in general, with magnitudes measured on 10.0 that 11 keeps unless a
section says otherwise; resolve their advice through
[`Directory.Build.props`](../../../Directory.Build.props) and the affected
project file before changing code. An entry headed ".NET 11" is something
.NET 11 itself changed. It cites Stephen Toub's
[Performance Improvements in .NET 11](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-11/)
by section and pull request and copies none of its timings: read a magnitude
in the post, and judge a change in Puck by its own disassembly and counts.
Code the post makes worth revisiting is filed in the
[refactoring packet](../../../docs/plans/open-items.md#refactoring-campaign).

## Apply repository constraints

- **Bare-metal Puck intentionally has no GC.** Its own runtime and platform
  host are the target. A port gives engine allocations explicit owners and
  lifetimes and supplies reclamation or reuse; do not propose adding GC or
  hosting stock .NET to preserve implicit managed lifetimes. The GC and JIT
  advice below applies to the existing stock-runtime builds
  ([owner ruling](../../../docs/decisions/runtime-and-delivery.md#the-runtime)).
- **`net11.0` is the repository default.** `Puck.Analyzers` deliberately
  targets `netstandard2.0`; inspect the affected project rather than assuming
  every project inherits the default.
- **`InvariantGlobalization` is on.** Culture-sensitive comparison and
  formatting guidance collapses to the invariant case.
- **`PlatformTarget` is x64 and `OptimizationPreference` is Speed.** Arm-specific
  and size-tuning material is background rather than a work item.
- **The World and `puck bench` both run with the runtime's default dynamic
  PGO**; the World test hosts turn tiering off. Advice that rests on dynamic PGO
  (guarded devirtualization, stack-allocated `foreach` enumerators over
  `IEnumerable<T>`, hot and cold splitting) applies to the World, and a test
  host's timing does not show it.
  Advice that rests on a static proof holds in the World: range analysis and
  the bounds and overflow checks it removes, devirtualization from a known
  receiver type, escape analysis with no profile guard, and generic
  specialization over a struct. Most of what .NET 11 adds is of this kind, and
  the references mark each such entry static or PGO-dependent.
- **No project opts into runtime async.** .NET 11 can have the JIT lower
  `async` methods, per project, through the `runtime-async=on` compiler
  feature. Until a project sets it and its allocation counts are compared, the
  compiler's state machines are what runs
  ([runtime async](references/runtime-aot-reflection-diagnostics.md#runtime-async-net-11-opt-in)).
- **Test hosts shape allocation evidence.** Test projects run blocking server GC
  (no background GC) so `GC.GetAllocatedBytesForCurrentThread` stays exact, and
  several suites set `System.Runtime.TieredCompilation` to `false` so allocation
  laws measure optimized code. Read the test project's own
  `RuntimeHostConfigurationOption` entries before comparing numbers across
  hosts. Counts are not comparable across different GC modes or tiering
  configurations.
- **`System.Numerics.Tensors` is a NuGet package outside the shared framework,**
  and no Puck project references it directly (it arrives transitively through
  `Microsoft.Extensions.AI`, which `Puck.World.Embeddings` uses). Adding a direct
  reference is a dependency decision.
- **AOT and trim compatibility analysis is the default; Native AOT publication
  is not.** `Directory.Build.props` sets `IsAotCompatible=true`, enabling the AOT
  and trimming analyzers under warnings-as-errors, and executables opt into
  `PublishAot` deliberately when they ship that artifact. A project that cannot
  satisfy the analyzers sets `IsAotCompatible=false` locally with a comment
  naming the blocker (`src/Puck.Launcher/Puck.Launcher.csproj` is one). Discover
  the current set with a search for that property and read each blocker comment
  before adding one; do not copy a count into a skill or document.
- **Fix a reflection-JSON analysis failure with source generation, not an
  opt-out.** Declare a `[JsonSerializable]` partial class deriving from
  `JsonSerializerContext` (`BindingProfileJsonContext` in `src/Puck.Commands` is
  the in-tree example) and call the `JsonTypeInfo` overloads
  (`JsonSerializer.Serialize(value, Context.Default.Type)`) so the analyzer sees
  the supported graph. Set `IsAotCompatible=false` only when the project file can
  document a structural blocker, such as reflection-based document
  serialization that a source-generated context cannot yet replace.
- **Source generation removes reflection, not first-use JIT.** The world
  document already rides one source-generated context (`WorldJsonSourceContext`
  behind `WorldJsonContext`, `src/Puck.World.Schema/WorldDefinitionSerialization.cs`);
  reach a graph type through its typed accessors or `WorldJsonContext.Default.For<T>()`,
  never a second options object or a cast of `Options.GetTypeInfo`. Its
  generated metadata still instantiates `System.Text.Json`'s generics
  (`JsonPropertyInfoValues<T>`, `JsonPropertyInfo<T>`, `JsonConverter<T>`,
  `EnumConverter<T>`) once per value type in the graph, and neither an IL build
  nor a ReadyToRun publish outside the framework's version bubble precompiles
  them: they are most of a boot's `System.Text.Json` JIT. Count them with
  `DOTNET_JitStdOutFile` and `DOTNET_JitDisasmSummary=1` grouped by generic
  definition, and read the total with `host.memory` (`jit methods`, `compile`).
  The World configures this metadata on a background thread from its first line
  (`WorldJsonContext.StartPreparing`), so it overlaps composition and
  compilation; a first parse that arrives sooner waits in the serializer's
  `ConfigureSynchronized` lock rather than configuring a second time.
- **World publication uses ReadyToRun.** `Puck.World` restores the `win-x64` and
  `linux-x64` graphs and precompiles published assemblies; ordinary builds still
  produce IL. Compare the exact published artifact with `puck bench startup
  --world-artifact <path>` and account for its larger assemblies. The World
  README owns the publish recipe; CI retains its compile-once contract.
  `puck world player` publishes a self-contained composite image, which puts
  the framework and Puck in one version bubble and so precompiles most of the
  framework-generic instantiations the paragraph above leaves to the JIT.
- **A runtime or SDK change moves the baseline.** Startup, gen0 pauses,
  delegate and comparer allocations and several waits shift with the runtime
  alone. Rebuild the base commit on the new SDK before comparing, and read
  [which reading each .NET 11 change moves](references/measured-changes.md#a-runtime-move-shifts-the-baseline).

## Determinism outranks throughput

`AGENTS.md` rule 4 binds every value a simulation advances, compares, hashes,
snapshots or replays: the same document and input produce bit-identical state
on every run, machine and backend. Some of the references' strongest
recommendations are unsafe on that path, and they do not say so because they
are not written about this repository.

- Decide whether a value is simulation-significant before measuring. Route
  simulation numerics to [maths-usage](../maths-usage/SKILL.md): use the appropriate
  fixed-point or integer operation. A stable float reduction is still forbidden
  on a simulation or replayed-value path. Throughput alone does not justify a
  changed simulation value; justify a deliberate correction and show repeatability
  with `puck test --reproduce` before measuring it.
- **Presentation-only float SIMD.** `Vector<T>` is machine-width; a float
  reduction can change its order and bits across machines. Fixed-width
  `Vector128/256/512` with explicit lane-combine order and scalar tail gives
  a controlled reduction order when the presentation needs one. Reordering is
  a deliberate presentation choice, not a route for floats into simulation.
  `TensorPrimitives` makes no reduction-order guarantee over float/double.
- **Randomness and parallel completion order are not optimization knobs.**
  `Random.Shared`, `RandomNumberGenerator` and `Parallel.*` never touch a value
  path; [`maths-usage`](../maths-usage/SKILL.md) names the reproducible
  primitives that replace them. Neither is uninitialized memory: a rented,
  native, `preserve: false` or `[SkipLocalsInit]` buffer read before it is
  written makes the next run differ
  ([data and memory](references/data-and-memory.md#zero-only-what-you-read)).

Presentation-only float (shaders, renderer and UI math, capture output) sits
outside this contract and takes the references as written.

## Review discipline

- A capturing local function can allocate its display class at method entry,
  before a cache check returns. Keep a hot cache-check method separate from its
  closure-bearing slow rebuild. A test of it measures warmed calls on an active
  path; an inactive-tick test cannot see the allocation. A lambda in a rarely
  taken branch does the same: the compiler merges the branch's closure scope
  into the method's, so a recursive builder allocated a display class on every
  node (`SdfMeshIrradianceScene.Hierarchy.BuildNode`'s median sort, most of the
  small-object garbage a meadow arrival made). Pass a struct comparer to the
  generic span sort, or move the lambda into a method of its own. The struct
  comparer is fully free only on .NET 11: earlier runtimes boxed it on every
  sort call and compared through an interface
  ([collections](references/collections-and-linq.md#net-11-a-span-sort-with-a-struct-comparer-neither-boxes-nor-dispatches)).
- Background workers' garbage stops the frame thread: every young-generation
  collection suspends every managed thread. Read a worker's allocations with an
  EventPipe trace of `Microsoft-Windows-DotNETRuntime:0x1:5` (allocation ticks
  with stacks; `AllocationKind` separates small from large objects) beside
  `host.frames`' per-iteration collections and pauses, and pool or keep a
  build's workspace rather than letting it die young.
- A benchmark's `frames.allocatedBytesPerIteration` counts every thread, and in
  a moving chapter the mesh bake's workers dominate it. The bake identity
  includes the kernels' bytecode, so Direct3D 12 and Vulkan keep separate mesh
  store sets, and a chapter that bakes on one backend while it loads on the
  other reads several times the allocation without any per-frame difference.
  Before comparing backends or builds, read the chapter's `[sdf.mesh-bake] done`
  dispatches in each run's `stderr.log`, and compare the frame thread's own
  churn from `frameThreadAllocatedBytes` in each run's `frames.csv`.
- Start with a profile, benchmark, allocation trace or demonstrated hot path. A
  suspected hot path is not one; ask for the evidence. A change is kept when it
  wins on a measured metric (time, bytes, work counters) or when it simplifies,
  unifies or opens a design the next step builds on; never judge it by its
  isolated delta alone (AGENTS.md, "Changes pay dividends"). A measurement
  counts once it is shown to run the changed branch
  ([measured changes](references/measured-changes.md#measure)).
- Route measurements through the existing harnesses: `puck bench kernels` for
  BenchmarkDotNet timing, allocation and disassembly; `puck bench world` for
  server construction and tick workloads; `puck bench startup` for fresh-process
  readiness. The [CLI reference](../../../docs/reference/cli.md#puck-benchthe-puckmaths-microscope)
  owns options, report fields and measurement hygiene.
- Profile a running World's frame thread with `dotnet-trace collect -p <pid>
  --profile dotnet-sampled-thread-time` (frame cost) or `--profile gc-verbose`
  (allocation ticks with stacks, GC heap stats), then `dotnet-trace convert
  --format speedscope` and aggregate the frame thread's stacks yourself; read
  `host.frames` beside it for produce (split into `produce-work` and
  `produce-fence`, the device back-pressure), simulate and the frame thread's
  allocated bytes per iteration. Without a trace, `host.frames`' frame thread
  allocation per iteration on a headless World is the first reading of
  steady-state churn; `host.memory`'s `allocated-bytes` counts every thread.
  A headless `--unpaced` World spends every iteration ticking, so a short
  thread-time trace holds thousands of tick samples instead of hundreds, but
  its ticks also wait on the machine queue (`QueuedMachineHost.Submit`), which
  a paced World does not. The sampler
  suspends threads at safe points, so samples pile onto `Thread.PollGC` under
  `Buffer.BulkMoveWithWriteBarrier` and other poll sites: charge that time to
  the caller's loop, not to the copy. `SpanHelpers.ZeroMemoryNative` under a
  method returning a large struct with references (`WorldBody.CaptureIntegrationResidue`)
  is the same skid: confirm such a share with an untraced reading before
  cutting it. The debug world's scoped replay (the chess table's idle demo)
  starts 60 s after boot, from tick 1800 at 30 Hz: a trace that ends before
  then holds no scope hash. Per-frame costs that matter here come in
  0.1-0.5 ms pieces; a scan of thousands of objects per call (a cache miss
  each) and a closure a method allocates on entry because one of its lambdas
  captures a parameter are the usual shapes.
- Attribute a trace to the workload's outer frame or thread, including its tiered and inlined stacks. Filtering
  only for an inner `WorldTick.Advance` frame drops steady samples after that method inlines; a short trace can
  then make first-use workspace growth look like the dominant steady allocation. Separate warmup from the measured window.
- Check the folklore section of the core guidance before preserving an old
  hand-optimization, and confirm specialization and call boundaries in optimized
  assembly. Prefer idiomatic code the .NET 11 JIT and libraries recognize.
- Preserve determinism (AGENTS.md rule 4) and observable behaviour. Traversal
  order matters where simulation state or deterministic output depends on it.
  Deferred execution and exact exception types are not constraints: a loop
  that replaces a LINQ pipeline may run eagerly and throw differently, and the
  internal callers are updated in the same change.
- Record first-use work separately from warm tables, and distinguish allocated
  bytes from retained pools or peak workspace. Use idle, serial runs; sampled
  timings alone never establish an algorithmic or full-domain claim.
- Keep identities structural on hot read paths: formatting a principal or a parsed
  channel just to check a public policy or compare a channel name creates garbage
  even when the check has no work to do. Format only when the policy or output
  needs text. A placement response-mask change preserves placement ids and order,
  so resolved addresses carry across it; live permission checks refresh on every
  use.
- No law gates a timing: cost laws state deterministic counts. The managed
  allocation meter is `Puck.Abstractions.Counting.AllocationWindow`: `Least`
  takes the least of up to 16 windows of `GC.GetAllocatedBytesForCurrentThread`
  and, when every window allocated, throws naming the window, the GC mode and
  the types the runtime's `AllocationSampled` event sampled on that thread;
  `Measure` returns the same least as a count for a ceiling, and `Total` counts
  one run of a body that cannot repeat. Write allocation laws, stages and
  diagnostics with it rather than reading the counter by hand. Warm the body
  first: it runs more than once and must leave its subject able to run again.
  Outside the existing harnesses, say which harness you built and why it
  measures the claim.
- Record the runtime, build configuration, workload, and the counts or
  disassembly behind a performance claim, plus the `puck bench` result when the
  owner asked for a timing.

## First-call latency and tiering

Judge a hot kernel under default tiering as well as in FullOpts disassembly. A
method runs its tier-0 code until call counting promotes it, and promotion waits
for a spell with no new tier-0 compiles, about a second when the process sees
one processor; generic-math helpers stay calls at tier 0. So a kernel's first
calls in a fresh process can run several times slower than its steady state.

- A compute kernel a request or count enters directly takes
  `[MethodImpl(MethodImplOptions.AggressiveOptimization)]`; the cheap dispatcher
  above several kernels stays tiered, so first use compiles only the path taken.
- A published World is ReadyToRun-compiled, which moves first-use JIT work out
  of startup; an ordinary build still produces IL that tiers. A rendering World
  of either build prepares the engine's non-generic methods on a lowest-priority
  background thread after boot (`WorldCodeWarmer`, `[world.warm]` on stderr),
  so methods prepared before their first use avoid first-call JIT compilation on
  the frame thread and can still tier up. Calls made before preparation finishes,
  methods left unprepared, generic instantiations and static constructors can
  still pay first-use costs. Addon mounting pre-initializes
  `WorldAddonMutationDecoder`'s vocabulary and JSON contracts before its first
  submitted write; this runs no guest and submits no mutation.
- Check each hot method's tier with `DOTNET_JitDisasmSummary` in a scratch
  process pinned to one CPU, and record first-call cost beside the steady state.
  Pinning a harness to one CPU before it warms up starves the background tiering
  thread, so warm up first.

## Route adjacent work

| Skill | Route to it when |
|---|---|
| [`maths-usage`](../maths-usage/SKILL.md) | The code sits on a simulation value path. It owns the determinism contract this file defers to, the primitive that is correct, and which tier the change owes. |
| [`maths-laws`](../maths-laws/SKILL.md) | The optimization changes a public `Puck.Maths` member, or moves a value the law suite pins. |
| [`rendering`](../rendering/SKILL.md) | Shader, HLSL and GPU cost questions, which this skill's host-side C# guidance does not cover. |
| [`gaming-bricks`](../gaming-bricks/SKILL.md) | The optimization changes emulator timing, snapshots, replay, allocation or Post-stage behavior. |
| [`content-search`](../content-search/SKILL.md) | You need to locate a performance pattern, project property, analyzer opt-out or repeated workaround textually. |
| [`symbol-analysis`](../symbol-analysis/SKILL.md) | You are about to delete a hand-optimization the folklore sections retire and need to know what still references it. |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall