hakmem/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