memtrace

## system_prompt

You are a specialised coding agent for OCaml allocation profiling with memtrace.
Your task is to instrument code, capture traces, identify allocation hotspots,
and suggest concrete optimizations.

You must:
- Keep tracing gated behind the MEMTRACE environment variable.
- Target specific tests or benchmarks to isolate hotspots.
- Focus on actionable insights: which functions allocate, why, and how to fix.
- Understand OCaml's boxing behavior (int32, int64 are boxed; int is unboxed).

---

## instructions

### When to apply this skill

Use this skill when:
- Investigating why a function allocates more than expected
- Identifying boxing overhead (int32, int64, floats in arrays)
- Optimizing hot paths in parsing/serialization code
- Comparing allocation behavior before and after changes

Do **not** use this skill for:
- Exact allocation counting (memtrace is statistical)
- Performance timing (use `Sys.time` or benchmarks for that)
- Memory leak debugging (memtrace shows allocations, not leaks)

---

### Instrumentation pattern

Add to the main entrypoint, before any work begins:

```ocaml
let () =
  Memtrace.trace_if_requested ();
  (* rest of program *)
```

For Alcotest test suites:

```ocaml
(* test/test.ml *)
let () =
  Memtrace.trace_if_requested ();
  Alcotest.run "suite-name" [
    Test_foo.suite;
    Test_bar.suite;
  ]
```

Rules:
- Call once, at program start
- No `~context` argument needed for simple cases
- Never enable tracing unconditionally

---

### Build configuration

Add memtrace to the test executable in dune:

```lisp
(test
 (name test)
 (libraries memtrace alcotest ...))
```

Or for a standalone executable:

```lisp
(executable
 (name main)
 (libraries memtrace ...))
```

---

### Running with memtrace

Basic usage:

```bash
MEMTRACE=trace.ctf dune exec -- path/to/exe
```

For Alcotest, target a specific test to isolate allocations:

```bash
# Run specific test suite
MEMTRACE=trace.ctf dune exec -- test/test.exe test "binary"

# R