hakmem/docs/archive/BUG_FLOW_DIAGRAM.md

# Bug Flow Diagram: P0 Batch Refill Active Counter Underflow

Legend
- Box 2: Remote Queue (push/drain)
- Box 3: Ownership (owner_tid)
- Box 4: Publish/Adopt + Refill boundary (superslab_refill)

Flow (before fix)
```
free(ptr)
  -> Box 2 remote_push (cross-thread)
      - active-- (on free)           [OK]
      - goes into SS freelist        [no active change]

refill (P0 batch)
  -> trc_pop_from_freelist(meta, want)
      - splice to TLS SLL            [OK]
      - MISSING: active += taken     [BUG]

alloc() uses SLL

free(ptr) (again)
  -> active-- (but not incremented before) → double-decrement
  -> active underflow → OOM perceived
  -> superslab_refill returns NULL → crash path (free(): invalid pointer)
```

After fix
```
refill (P0 batch)
  -> trc_pop_from_freelist(...)
      - splice to TLS SLL
      - active += from_freelist      [FIX]
  -> trc_linear_carve(...)
      - active += batch              [asserted]
```

Verification Hooks
- One-shot OOM prints from superslab_refill
- Optional: `HAKMEM_TINY_DEBUG_REMOTE_GUARD=1` and `HAKMEM_TINY_TRACE_RING=1`