# Field notes — smarm context-switch session (v0.8)

Notes from one real session using llmdbg v0.8 to profile and verify smarm's
naked-asm context switch (the TLS-accessor perf question and the XMM-not-saved
correctness question). Recorded as friction-and-wishlist, not a defect report —
nothing here blocked the work; every rough edge had a workaround.

## What worked

- **Demangling.** `addr("switch_to_scheduler")` resolving directly meant zero
  `nm | grep` for mangled names whose hash changes every rebuild. Biggest
  single quality-of-life win.
- **`trace({over, range, capture})`.** The capture closure returning a
  structured record per step (`{pc, insn, len, is_call}`) and letting the
  caller format it is the right shape — produced a clean 16-line shim trace in
  one pass.
- **`next()` vs `step()`.** The distinction the docs emphasise is exactly the
  axis this task needed: stepping *into* the accessors (164 insns of debug-build
  `LocalKey` ceremony) vs *over* them is the difference between readable and
  unreadable, and `step()` *through* the stack-swapping `ret` is what let me
  walk the switch itself.
- **The worked example** (`examples/smarm_ctx_switch_next.js`) was close enough
  to the real task to adapt directly. Good investment.

## What bit me

- **Range checks on `state.pc` are treacherous when helpers sit adjacent to the
  function under test.** `set_actor_sp` lived at `sched+0x50`, *inside* my
  `+0x60` window, so a "stop when pc returns to the shim" loop terminated the
  instant it entered the accessor. Cost me two attempts before I abandoned
  range-based exit detection and dumped a flat `step()` stream to count by eye.
  The missing primitive is symbol *extent* (start ≤ pc < start+size), not
  symbol *address*.
- **The `push rbx` consumed-by-breakpoint quirk** is correctly documented, but
  I had to re-apply "the first observed instruction is the second one" mentally
  at every session. A documented footgun is still a footgun.
- **No float/vector register access.** The XMM-not-saved verification had to
  leave llmdbg entirely and fall back to `objdump` to confirm the compiler
  spills live XMM around the switch call. For a tool whose reason for existing
  is x86-64 context-switch correctness, watching `xmm0..15` across a switch
  feels squarely in scope — it would have turned a static inference into a
  dynamic proof (XMM dead at switch entry, live again after reload).

## Wishlist (rough priority order)

1. **Symbol-extent queries** — `symStart(pc)` / `symSize(pc)`, or an
   `inFn(pc, "name")` membership test. Fixes the range-check footgun directly.
   This is the highest-value add for asm work, where "am I still inside this
   function" is a constant question. Pure-JS-expressible if the native `sym`
   layer exposes extents.
2. **`countTo(stop, {over})`** — step until an address/predicate and return
   just the instruction count, instead of hand-rolling `let n=0; while(...){
   step(); n++ }` and getting the boundary wrong. Counting per-call instruction
   cost was the core measurement of this task and had no first-class support.
   Pure-JS prelude helper.
3. **XMM/SSE register reads** — `state.xmm[i]` or `reg("xmm0")`. Needs
   Rust-side support (ptrace `GETFPREGS`/`xsave`). In scope for this tool's
   purpose.
4. **Prologue-aware breakpoints** — a mode (or `bp.setAfterPrologue()`) that
   removes the "first instruction eaten" caveat rather than documenting around
   it.
5. **`hexdump(addr, n)`** — peek at raw memory, e.g. a freshly-built initial
   actor stack from `init_actor_stack`. Pure-JS over a `readMem` primitive.
   Nice-to-have; didn't strictly need it this round.

## Suggested next step

Items 1, 2, and 5 are pure-JS and fit the SPEC ethos ("everything expressible
in JS lives in JS") — they belong in `src/prelude.js` and would be a clean v0.9
with no Rust changes (assuming `sym` extents and a `readMem` primitive are
reachable from JS). Items 3 and 4 need native support and are larger.