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

references/measured-changes.md

View on GitHub
# Measured changes

Read this before landing a change whose reason is speed or allocation. Back to
[../SKILL.md](../SKILL.md). It distils the review record of ASP.NET Core's
agent-driven performance effort
([dotnet/aspnetcore#70219](https://github.com/dotnet/aspnetcore/issues/70219),
97 PRs). Its gains are each author's own microbenchmark on unmerged PRs; the
techniques and the defects review found are what transfer. Each technique cites one PR and one place in Puck.

## What a change is judged by

- **Changes pay dividends** (AGENTS.md). 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. One that does neither is dropped,
  and the hand-back says so.
- **Compatibility practices do not carry over.** Exact exception types and
  their timing, constructor order around virtual calls, deferred execution, "no
  API change" and "the smallest possible change" protected ASP.NET's customers.
  Puck has none (rule 5): change the type and update every caller in the same
  change. What holds is determinism (rule 4) and observable behaviour: what a
  World shows, writes, hashes, persists or sends.

## Measure

- **Stop a redirected trace explicitly and collect rundown.** `dotnet-trace`
  does not treat Enter as cancellation when stdin is redirected
  ([collector source](https://github.com/dotnet/diagnostics/blob/main/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs)).
  Use its bounded duration, or stop the EventPipe session through DiagnosticsClient,
  and let the collector drain while the target remains alive. Killing a collector
  can leave a readable trace whose missing rundown makes managed stacks unusable.
  Convert and analyze one trace sequentially: TraceEvent readers share its
  `.etlx.new` intermediate, so concurrent readers can collide while creating it.
  Inspect the output artifact too; a converter can print an exception and still
  exit successfully.
- **A lane proves a win on load-independent counters:** allocated bytes
  (`AllocationWindow`, `puck bench world`'s allocation rows), march and ray step
  counts, `world.budget` work counts, and `puck bench world`'s contact counts.
  They hold beside other lanes' builds; a timing taken there does not
  ([the frame bar](../../../../docs/plans/engine-job-system.md#what-the-measurements-say)).
- **Wall-clock claims are interleaved A/B rounds** against a base build the
  lane built: base, candidate, base, candidate, reversed once, three pairs or
  more, every round reported. They run in the lead's quiet window through
  `puck measure run` or `puck lease quiet`, never beside other lanes' work
  ([orchestration](../../orchestration/SKILL.md#spend-verification-not-writing)).
  Read `BenchReport.HostLoad` before interpreting the result: the reservation
  coordinates leased work, and another test launched without a lease can still
  contaminate it. A report that records another heavy test is not quiet-window
  timing evidence; retain it and repeat only after that work has ended.
- **Prove the steady state runs the changed branch,** not a warm cache or a
  default path: count the changed path's calls, or break the change and see
  the number move. Two of #70158's six benchmark headers took the known-header
  branch, #70146 measured the CNG encryptor on Windows instead of the managed
  one it changed, and #70174's and #70175's tests passed with the cache
  reverted.
- **A motion harness must advance the production inputs.** A zero changed-pose
  count is not evidence of static foliage until the state mirror has installed
  the document's initial cells and the creation pool's clock has advanced.
  `WorldSceneEmitter.Tick` and `WorldCreationInstances.Tick` are separate doors;
  advancing only the former left a placement census motionless. The corrected
  production capture moves thousands of independent authored grass slots. Label
  a placement-only census separately from the native World's body population.
- **Measure where tiering matches the target.** The World process and
  `puck bench kernels` and `puck bench world` run with the default dynamic PGO,
  and the World test hosts turn tiering off. A win that rests on PGO (guarded
  devirtualization, a stack-allocated enumerator) shows in the World and the
  bench but not in a test host's timing.

## A runtime move shifts the baseline

A reading taken on one runtime and compared with a reading on the next includes
the runtime's own gains. Keep them apart from the workload's: rebuild the base
commit on the new SDK and compare against that, never against a number recorded
on the old one. These .NET 11 changes reach Puck with no source change
([Performance Improvements in .NET 11](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-11/),
cited by section and pull request).

| Puck reading | What moves it | Post section; pull request |
|---|---|---|
| Allocated bytes that include a delegate | Every CoreCLR delegate is 8 bytes smaller | Deabstraction; dotnet/runtime#99200 |
| Allocated bytes of a span sort with a struct comparer | The comparer is not boxed, and `Compare` inlines. Since .NET 10 boxed a struct comparer on every span sort (per the post), the irradiance hierarchy's median split (`CentroidOrder`) boxed its comparer once per split node; its trace has not been retaken | Strings and Spans; dotnet/runtime#116109 |
| A gen0 pause | Young collections skip old `ConditionalWeakTable` entries | Write Barriers and Garbage Collection; dotnet/runtime#78746 |
| `puck bench startup` | ReadyToRun precompiles default comparer initialization, and the host builds its assembly list with less work | Startup and Deployment; dotnet/runtime#126204, #123568, #123919, #125251 |
| Thread-pool threads while a child process runs | Redirected stdout and stderr are overlapped reads on Windows, so `ChildProcess`'s two pumps hold no thread | I/O; dotnet/runtime#125643 |
| Waits on the tick path | `Monitor.Wait` and `Monitor.Pulse` drop a table lookup (the machine queue, the GPU fence waits) | Threading; dotnet/runtime#129083 |
| Code size and time of checked arithmetic and `BinaryPrimitives` reads | Overflow and bounds checks a guard makes redundant are removed | Bounds Checks; dotnet/runtime#124147, #124184, #127488 |
| Reading an indented document | `Utf8JsonReader` skips whitespace runs in vector steps | JSON; dotnet/runtime#129701 |
| Bake and capture float | Scalar `Half` casts and the `Dot` methods lower to cheaper instructions | Intrinsics; dotnet/runtime#127094, #125666 |
| Arbitrary-width arithmetic | `BigInteger` runs on pointer-width limbs with better multiply, divide and `ModPow` | Numerics; dotnet/runtime#125799 |
| Invariant casing of ASCII text | A managed ASCII path | Globalization; dotnet/runtime#120685 |
| Puck's regexes (mostly `[GeneratedRegex]`, in tooling, engine and World code; the switch dispatch reaches only the `Compiled` minority) | A final cleanup pass, whole-literal prefix search, switch dispatch under `Compiled` | Strings and Spans; dotnet/runtime#125289, #124736, #122959 |
| Launching a child on Linux | Arguments and environment are marshalled into one native block each | Diagnostics; dotnet/runtime#126201 |

## Know what the change changed

- **Simulation:** compare state hashes from both builds over the touched
  scenarios. Equal hashes mean the change moved no result; a deliberate
  correction is re-recorded with its reason (rule 4); anything else is a bug.
- **Derived bytes:** compare digests of bake stores, payloads and captures
  across the builds, as #70125 compared every serialized test output.
- **No scenario reaches the path:** run old against new in a scratch harness
  over random and boundary inputs (#70157: 150,924 headers). It is commit-body
  evidence, not a committed test.
- **Drift review kept finding:** a skipped call that observed cancellation
  (#70180) and a decoder that turned lenient (#70142, a security defect).
  Change either on purpose when the design is better; never by accident.

## Techniques

| Technique | PR | In Puck |
|---|---|---|
| Decide before the expensive path. A prefilter may give only false positives, and a miss never repeats the fast path's work | #70119 | `RuleEvaluator.EvaluateOnceCore` skips bindings and gate when nothing the rule reads changed ([source](../../../../src/Puck.State.Rules/Evaluation/RuleEvaluator.cs)) |
| Cache a derivation keyed by exactly what it reads, and cache an absence when absence is the common answer | #70220 | `RuleLatch.RuleState` keys a rule's schedule by evaluator and compiled rule ([source](../../../../src/Puck.State.Rules/Evaluation/RuleLatch.cs)); `WorldPlacementStamper.Queryable` includes the composed parent frame and distribution seed, even when the child row is unchanged |
| Hoist keyed setup out of a repeated operation | #70157 | `SdfWorldTables.UpdateTablesSignature` hashes each region once with `XxHash3` ([source](../../../../src/Puck.SdfVm/SdfWorldTables.Cadence.cs)) |
| Size first, then write once into the final destination | #70134 | `SdfWorldTables.StageChangedDraws` writes a draw straight into its staged record ([source](../../../../src/Puck.SdfVm/SdfWorldTables.MeshRegion.cs)) |
| Remove re-copies and rescans of finished work | #70139 | `SdfMeshPathBake.Pending`'s done-through cursor ([source](../../../../src/Puck.SdfVm/SdfMeshPathBake.cs)) |
| Allocate rarely used state on first use | #70189 | `SdfFieldEvaluator`'s point walk builds its reach scratch on a thread's first walk ([source](../../../../src/Puck.SignedDistance/Queries/SdfFieldEvaluator.PointWalk.cs)) |
| A `static` lambda with a state argument, not a capturing closure | #70185 | `WorldSchema.ResolveDescriptionForMember` ([source](../../../../src/Puck.World.Schema/WorldSchema.cs)) |
| Loop over the concrete collection where an interface enumerator boxes | #70147 | `SdfMeshPathBake` indexes copy membership when topology changes; `SdfMeshDresser` reads retained bindings instead of enumerating all copies per group |
| Format text only when it is emitted | #70178 | `GenlockPhaseAligner.LogPhase` checks `IsEnabled` first ([source](../../../../src/Puck.Launcher/GenlockPhaseAligner.cs)) |
| Look up by span through an alternate lookup, and decode strictly | #70142 | `CellKeyTable.TryResolve` ([source](../../../../src/Puck.State/CellKey.cs)) |
| Cache `SearchValues` statically; never rebuild one per call | #70224 | `IdentifierRules.ReservedCharacters` ([source](../../../../src/Puck.State/SafeName.cs)) |
| A scan over a few fixed entries beats hashing; one over a list that grows with the world is the quadratic | #70209 | Bake demand and dressing share one copy-membership index, replacing the old per-group scan over all copies ([data and memory](data-and-memory.md#a-scan-per-item-is-a-quadratic)) |
| Publish shared state as an immutable object in one reference write | #70176 | `CodeDerivedTable` swaps a whole generation: an old in-flight derivation publishes only into its detached weak table ([source](../../../../src/Puck.Abstractions/CodeDerivedTable.cs)) |
| Scratch its owner keeps and reuses, over a shared pool | #70159 | `WorldBody.StepScratch` ([source](../../../../src/Puck.World.Server/WorldBody.SweepRefusal.cs)) |

## Hazards review found

- **Never read a byte you did not write** (#70146 derived wrong keys from a
  rented array it assumed was zero); in Puck it is a determinism defect
  ([data and memory](data-and-memory.md#zero-only-what-you-read)).
- **A rent never returned costs more than an allocation** (#70195).
- **A borrow ends before its owner grows, resets or returns the storage,** and
  a writer handed out supports every member its interface promises (#70228).
- **Bound every capacity taken from input** (#70166 capped a list sized from a
  comma count).
- **A cache key that omits an input goes stale** (#70141 took two review rounds).
- **Clearing a shared table is not a generation boundary.** A derivation that
  started before the clear can publish after it. `CodeDerivedTable` holds one
  immutable generation through lookup, derivation and publication; replacing the
  table prevents old work from contaminating the new code's cache.
- **Materialize a query before storing it in a long-lived object** (#70183).
- **Key a fast path on the compiled canonical form,** never on how an author
  spelled something or which world runs (AGENTS.md, "Ergonomic is optimal").
- **Seal and change the type** rather than guarding a fast path with
  `GetType() == typeof(X)` beside a kept slow path (#70126): in Puck the kept
  path is a second implementation.
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