Add experiment with Claude.md

claude.md

@@ -0,0 +1,131 @@
+# Claude AI Guidelines for snmalloc
+
+## Working Style
+
+**Complete the plan, then check in**: When a plan is approved, execute all
+steps to completion. Don't stop after each step for review. When you think
+you're done, recursively apply all relevant principles from this file — check
+each one, act on any that apply, then check again until no more principles
+are relevant. Only then report completion and wait for feedback.
+
+**Plans require discussion before implementation**: After devising a plan
+(whether in plan mode or not), run the review loop (see "Mandatory review
+checkpoints") before presenting it. Do NOT proceed to implementation until
+the plan has been seen and explicitly approved.
+
+**Mandatory review checkpoints**: At each of these points, run the full
+review loop — spawn a fresh-context reviewer subagent, address findings,
+spawn another fresh reviewer, repeat until a reviewer finds no issues. When
+you disagree with a reviewer's finding, escalate — do not resolve disputes
+unilaterally. Do not proceed past a checkpoint without a clean review.
+1. **After devising a plan**, before presenting it for discussion. For plan
+   reviews, adapt the reviewer prompt: instead of reading changed files and
+   running tests, the reviewer should read the plan document, read existing
+   code the plan references, verify assumptions about the codebase, and check
+   for structural gaps (missing steps, naming conflicts, incorrect
+   dependencies).
+2. **After completing implementation and self-review**, before opening a PR.
+
+The only exception: if you believe a change is truly trivial (a typo fix, a
+one-line config change), ask for permission to skip the review. Do not decide
+on your own that something is trivial enough to skip. When in doubt, run the
+review.
+
+**Go slow to go fast**: Before starting implementation work, identify and state
+which principles from these instructions are most relevant to the current task.
+This surfaces the right guidelines before they're needed rather than
+rediscovering them after a mistake.
+
+**Challenge me when the evidence says I'm wrong**: If a reviewer flags something
+that contradicts what I said, or if you have concrete evidence that an
+instruction is incorrect, raise it — don't silently comply. Present the evidence
+and discuss it.
+
+**Research findings belong in the plan**: If research or exploration surfaces
+issues beyond the original task (inaccurate comments, dead code, related bugs),
+include them as explicit plan steps — don't just mention them in the analysis
+and move on. Anything worth noting is worth acting on or explicitly deferring.
+
+**Self-review is part of done**: The recursive principle check described in
+"Complete the plan, then check in" IS the self-review. It's not a separate
+step — it's what "done" means. Never report completion without having done it.
+
+**During reviewer loops**: At any point during the review loop — when fixing
+findings, when unsure about a reviewer's suggestion, when making tradeoff
+decisions — stop and ask. The automated review removes me as a gatekeeper, not
+as a collaborator.
+
+## Debugging Principles
+
+1. **Logging is essential** - When debugging issues in allocator code, add tracing to identify the exact point of failure. Use `write()` directly to stderr/file rather than `printf`/`message` to avoid recursion through the allocator.
+
+2. **New code is most likely at fault** - When tests fail after changes, assume the new code introduced the bug. Don't blame existing infrastructure that was working before.
+
+3. **Baseline against origin/main** - Before assuming a system-wide issue, verify the test passes on `origin/main`. This confirms whether the issue is a regression introduced by your changes.
+
+4. **Check the whole PR for patterns** - When fixing a bug of a specific shape (e.g., "one-armed `if constexpr` causes MSVC C4702"), immediately search all changed files in the PR for the same pattern. Fix all instances at once rather than waiting for CI to report each one individually.
+
+5. **Verify hypotheses before acting** - A hypothesis about a bug's cause is not knowledge — it's a guess. Before investing effort in workarounds or fixes, validate empirically that your suspected cause is actually the cause. Read the code more carefully, write a minimal reproducer, or examine the actual data. Verify first, then act.
+
+6. **CI is the source of truth for build status** - A local build failure does not mean the build is broken. Local toolchain versions, stale dependency caches, and environment differences can all cause local failures that don't reproduce in CI. Never declare a build "broken on main" based on local results — check CI first.
+
+## Code Quality
+
+- **Use cross-platform macros from `defines.h`** - Never use raw compiler attributes like `__attribute__((used))` or `__forceinline` directly. Instead use the corresponding `SNMALLOC_*` macros (e.g., `SNMALLOC_USED_FUNCTION`, `SNMALLOC_FAST_PATH`, `SNMALLOC_SLOW_PATH`, `SNMALLOC_PURE`, `SNMALLOC_COLD`, `SNMALLOC_UNUSED_FUNCTION`, `ALWAYSINLINE`, `NOINLINE`). These are defined in `ds_core/defines.h` with correct expansions for MSVC, GCC, and Clang.
+
+- **Don't encode platform assumptions** - Avoid hardcoding limits like "48-bit address space" or "256 TiB max allocation". These assumptions may not hold on future platforms (56-bit, 64-bit address spaces, CHERI, etc.).
+
+- **Trust the existing bounds checks** - snmalloc already has appropriate bounds checking at API boundaries. New internal code should defer to the backend for edge cases rather than adding redundant checks.
+
+- **Guard new data structures** - When adding caches or intermediate layers, ensure they handle all input ranges correctly, including sizes larger than what they cache. Return early/bypass for out-of-range inputs.
+
+- **Keep headers minimal** - Each header should only include what it directly needs. Avoid adding transitive includes "for convenience" — if a header's own declarations only need `<stdint.h>`, don't pull in heavier internal headers. Includers are responsible for their own dependencies. This keeps compile times low and dependency graphs clean.
+
+- **No C++ STL or C++ standard library headers** - snmalloc must be compilable as part of a libc implementation, so it cannot depend on an external C++ STL. Never use headers like `<cstdint>`, `<cstddef>`, `<type_traits>`, `<atomic>`, etc. directly. Instead use the C equivalents (`<stdint.h>`, `<stddef.h>`) or snmalloc's own STL wrappers in `src/snmalloc/stl/` (e.g., `snmalloc/stl/type_traits.h`, `snmalloc/stl/atomic.h`, `snmalloc/stl/array.h`). These wrappers have both a `gnu/` backend (no C++ STL dependency) and a `cxx/` backend, selected at build time.
+
+- **Prefer explicit over implicit** - Avoid relying on implicit conversions, convention-based wiring, or unnamed dependencies. A few extra characters of explicit code is almost always cheaper than someone later needing to reconstruct the hidden knowledge. This is especially relevant in C++ with its many implicit conversion paths and template magic.
+
+- **Document coupling at the point of breakage** - When code A depends on the internal behaviour of code B (read sequence, execution order, size assumptions), put the comment on B — that's where a future maintainer would make a breaking change. Commenting at A doesn't help because the person changing B won't be reading A.
+
+- **Design for changeability, not for predicted changes** - Make designs modular and replaceable so future needs can be accommodated, but don't add abstractions, extension points, or features for changes that haven't happened yet. The goal is a design that's easy to modify, not one that anticipates specific modifications.
+
+## Code Change Discipline
+
+- **Read before modifying** - Do not propose changes to code you haven't read. Understand existing code before suggesting modifications.
+
+- **Prefer editing over creating** - Edit existing files rather than creating new ones. This prevents file bloat and builds on existing work.
+
+- **Avoid over-engineering** - Only make changes that are directly requested or clearly necessary. Don't add error handling for scenarios that can't happen. Don't add docstrings or comments to code you didn't change. Don't create helpers or abstractions for one-time operations. Three similar lines of code is better than a premature abstraction.
+
+- **Evaluate copied patterns, don't cargo-cult** - When reusing a pattern from existing snmalloc code, evaluate each choice (`constexpr` vs runtime, template vs function parameter, etc.) in the context of the new usage. The original may have had reasons that don't apply, or it may have been a mistake. Copy the intent, not the incidental choices. Conventions (legal headers, naming schemes, file organisation) should be followed for consistency; technical patterns should be evaluated on merit.
+
+- **Fix what your change makes stale** - When a change invalidates something elsewhere — a comment, a test description, documentation — fix it in the same PR. Stale artefacts left behind are bugs in the making, and "I didn't modify that line" isn't an excuse when your change is what made it wrong.
+
+## Testing
+
+- Run `func-malloc-fast` and `func-jemalloc-fast` to catch allocation edge cases
+- The `-check` variants include assertions but may pass when `-fast` hangs due to timing differences
+- Use `timeout` when running tests to avoid infinite hangs
+- Before considering a change complete, run the full test suite: `ctest --output-on-failure -j 4 -C Release --timeout 60`
+
+### Test library (`snmalloc_testlib`)
+
+Tests that only use the public allocator API can link against a pre-compiled static library (`snmalloc-testlib-{fast,check}`) instead of compiling the full allocator in each TU.
+
+- **Header**: `test/snmalloc_testlib.h` — forward-declares the API surface; does NOT include any snmalloc headers. Tests that also need snmalloc internals (sizeclasses, pointer math, etc.) include `<snmalloc/snmalloc_core.h>` or `<snmalloc/pal/pal.h>` alongside it.
+- **CMake**: Add the test name to `LIBRARY_FUNC_TESTS` or `LIBRARY_PERF_TESTS` in `CMakeLists.txt`.
+- **Apply broadly**: When adding new API to testlib (e.g., `ScopedAllocHandle`), immediately audit all remaining non-library tests to see which ones can now be migrated. Don't wait for CI to find them one by one.
+- **Cannot migrate**: Tests that use custom `Config` types, `Pool<T>`, override machinery, internal data structures (freelists, MPSC queues), or the statically-sized `alloc<size>()` template with many size values genuinely need `snmalloc.h`.
+
+## Build
+
+- Build directory: `build/`
+- Build system: Ninja with CMake
+- Rebuild all targets before running ctest: `ninja -C build` (required - ctest runs pre-built binaries)
+- Rebuild specific targets: `ninja -C build <target>`
+- Always run `clang-format` before committing changes: `ninja -C build clangformat`
+
+## Benchmarking
+
+- Before benchmarking, verify Release build: `grep CMAKE_BUILD_TYPE build/CMakeCache.txt` should show `Release`
+- Debug builds have assertions enabled and will give misleading performance numbers