hakmem/docs/FREE_SAFETY.md

Free Safety (Debug Guards)

Goal

• Detect invalid/double free and class mismatches early, with minimal intrusion on hot paths (debug‑only).

Envs

• HAKMEM_SAFE_FREE=1
  • Enable free‑time validations (SS range, block alignment/size/capacity, light freelist scan for duplicates).
• HAKMEM_SAFE_FREE_STRICT=1
  • Fail‑Fast (emit Tiny Ring + raise SIGUSR2) when invalid free is detected.

Checks (SuperSlab path)

• Pointer must map to a registered SuperSlab (registry lookup + magic check).
• Block alignment: (ptr - slab_base) % block_size == 0 and < block_size * capacity.
• Optional duplicate scan: traverse up to 64 nodes of meta->freelist to see if ptr is already present.
• Cross lookup note: the same virtual base may be reused by a different class after SS free/cache reuse.
  • Two consecutive free_enter with different classes on the same pointer likely means double free, not freelist corruption.

Checks (TinySlab path)

• Registry lookup + membership (ptr in [base, base+64KB)).
• Optional duplicate scan (same as above; beware of cost).

Ring Guidance

• Record free_enter before validation.
• On invalid free: record ring with pointer/class and boundary that failed; if STRICT then raise SIGUSR2.

Limitations

• No per‑block headers: we avoid storing tags in user memory; detection focuses on boundary and freelist duplication checks.
• Reallocate‑then‑free(UAF) after the pointer is reused may evade duplicate scan; STRICT mode is recommended when chasing crashes.