Skip to content

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

dotnet-performance

Unverified

Tunes Puck .NET 11 performance: allocation, gen0 pauses, data layout, false sharing, stackalloc, LINQ, Vector<T>, tiering, AllocationWindow, puck bench, AOT (IL2026). 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

AreaRead
Cross-domain mental model, pattern changes, API shortlist, folklorereferences/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 findsreferences/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 herereferences/data-and-memory.md
JIT, codegen, allocation, inlining, bounds checks, ISAreferences/jit-and-codegen.md
Collections, LINQ, Frozen/Immutable, CollectionsMarshalreferences/collections-and-linq.md
Strings, spans, search, regex, UTF-8, encodingreferences/strings-text-search.md
Numerics, SIMD, tensor APIs, randomness, threadingreferences/numerics-simd-threading.md
I/O, compression, networking, JSON, cryptoreferences/io-network-json-crypto.md
AOT, reflection, GC handles, diagnostics, DI, runtimereferences/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 and the affected project file before changing code.

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).
  • 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.
  • Puck.World sets TieredPGO=false (the TieredPGO property in Puck.World.csproj). The setting is process-wide, so every library a World loads runs without dynamic PGO, while puck bench runs in the CLI with it. Advice that rests on dynamic PGO (guarded devirtualization, stack-allocated foreach enumerators over IEnumerable<T>, hot and cold splitting) describes other hosts; for code the World runs, read the disassembly of the actual build before relying on it.
  • 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.

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: 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 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).

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.
  • 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).
  • 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 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

SkillRoute to it when
maths-usageThe 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-lawsThe optimization changes a public Puck.Maths member, or moves a value the law suite pins.
renderingShader, HLSL and GPU cost questions, which this skill's host-side C# guidance does not cover.
gaming-bricksThe optimization changes emulator timing, snapshots, replay, allocation or Post-stage behavior.
content-searchYou need to locate a performance pattern, project property, analyzer opt-out or repeated workaround textually.
symbol-analysisYou 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: 196kUpdated 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: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated 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: 192kUpdated Claude CodeCodexVerifiedInstall