Tiny: fix remote sentinel leak → SEGV; add defense-in-depth; PoolTLS: refill-boundary remote drain; build UX help; quickstart docs

Summary
- Fix SEGV root cause in Tiny random_mixed: TINY_REMOTE_SENTINEL leaked from Remote queue into freelist/TLS SLL.
- Clear/guard sentinel at the single boundary where Remote merges to freelist.
- Add minimal defense-in-depth in freelist_pop and TLS SLL pop.
- Silence verbose prints behind debug gates to reduce noise in release runs.
- Pool TLS: integrate Remote Queue drain at refill boundary to avoid unnecessary backend carve/OS calls when possible.
- DX: strengthen build.sh with help/list/verify and add docs/BUILDING_QUICKSTART.md.

Details
- core/superslab/superslab_inline.h: guard head/node against TINY_REMOTE_SENTINEL; sanitize node[0] when splicing local chain; only print diagnostics when debug guard is enabled.
- core/slab_handle.h: freelist_pop breaks on sentinel head (fail-fast under strict).
- core/tiny_alloc_fast_inline.h: TLS SLL pop breaks on sentinel head (rare branch).
- core/tiny_superslab_free.inc.h: sentinel scan log behind debug guard.
- core/pool_refill.c: try pool_remote_pop_chain() before backend carve in pool_refill_and_alloc().
- core/tiny_adaptive_sizing.c: default adaptive logs off; enable via HAKMEM_ADAPTIVE_LOG=1.
- build.sh: add help/list/verify; EXTRA_MAKEFLAGS passthrough; echo pinned flags.
- docs/BUILDING_QUICKSTART.md: add one‑pager for targets/flags/env/perf/strace.

Verification (high level)
- Tiny random_mixed 10k 256/1024: SEGV resolved; runs complete.
- Pool TLS 1T/4T perf: HAKMEM >= system (≈ +0.7% 1T, ≈ +2.9% 4T); syscall counts ~10–13.

Known issues (to address next)
- Tiny random_mixed perf is weak vs system:
  - 1T/500k/256: cycles/op ≈ 240 vs ~47 (≈5× slower), IPC ≈0.92, branch‑miss ≈11%.
  - 1T/500k/1024: cycles/op ≈ 149 vs ~53 (≈2.8× slower), IPC ≈0.82, branch‑miss ≈10.5%.
  - Hypothesis: frequent SuperSlab path for class7 (fast_cap=0), branchy refill/adopt, and hot-path divergence.
- Proposed next steps:
  - Introduce fast_cap>0 for class7 (bounded TLS SLL) and a simpler batch refill.
  - Add env‑gated Remote Side OFF for 1T A/B (reduce side-table and guards).
  - Revisit likely/unlikely and unify adopt boundary sequencing (drain→bind→acquire) for Tiny.

core/pool_refill.c

@@ -1,5 +1,7 @@
 #include "pool_refill.h"
 #include "pool_tls.h"
+#include "pool_tls_arena.h"
+#include "pool_tls_remote.h"
 #include <sys/mman.h>
 #include <stdint.h>
 #include <errno.h>
@@ -12,6 +14,26 @@ void* pool_refill_and_alloc(int class_idx) {
     int count = pool_get_refill_count(class_idx);
     if (count <= 0) return NULL;
 
+    // Refill boundary integration: try draining remote frees first.
+    // If we can satisfy from remote queue, avoid backend carve (OS pressure).
+    {
+        void* rchain = NULL;
+        int rgot = pool_remote_pop_chain(class_idx, count, &rchain);
+        if (rgot > 0 && rchain) {
+            // Pop one to return, install the rest into TLS
+            void* ret = rchain;
+            rchain = *(void**)rchain;
+            rgot--;
+            if (rgot > 0 && rchain) {
+                pool_install_chain(class_idx, rchain, rgot);
+            }
+            #if POOL_USE_HEADERS
+            *((uint8_t*)ret - POOL_HEADER_SIZE) = POOL_MAGIC | class_idx;
+            #endif
+            return ret;
+        }
+    }
+
     // Batch allocate from existing Pool backend
     void* chain = backend_batch_carve(class_idx, count);
     if (!chain) return NULL;  // OOM
@@ -34,65 +56,36 @@ void* pool_refill_and_alloc(int class_idx) {
     return ret;
 }
 
-// Backend batch carve - Phase 1: Direct mmap allocation
+// Backend batch carve - Phase 1.5a: TLS Arena with chunk carving
 void* backend_batch_carve(int class_idx, int count) {
     if (class_idx < 0 || class_idx >= POOL_SIZE_CLASSES || count <= 0) {
         return NULL;
     }
 
-    // Get the class size
-    size_t block_size = POOL_CLASS_SIZES[class_idx];
+    // Allocate blocks array on stack
+    void* blocks[64];  // Max refill count is 64
+    if (count > 64) count = 64;
 
-    // For Phase 1: Allocate a single large chunk via mmap
-    // and carve it into blocks
-    #if POOL_USE_HEADERS
-    size_t total_block_size = block_size + POOL_HEADER_SIZE;
-    #else
-    size_t total_block_size = block_size;
-    #endif
-
-    // Allocate enough for all requested blocks
-    size_t total_size = total_block_size * count;
-
-    // Round up to page size
-    size_t page_size = 4096;
-    total_size = (total_size + page_size - 1) & ~(page_size - 1);
-
-    // Allocate memory via mmap
-    void* chunk = mmap(NULL, total_size, PROT_READ | PROT_WRITE,
-                       MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
-    if (chunk == MAP_FAILED) {
-        return NULL;
+    // Carve from TLS Arena (Phase 1.5a)
+    int carved = arena_batch_carve(class_idx, blocks, count);
+    if (carved == 0) {
+        return NULL;  // OOM
     }
 
-    // Carve into blocks and chain them
+    // Chain the carved blocks
     void* head = NULL;
     void* tail = NULL;
-    char* ptr = (char*)chunk;
 
-    for (int i = 0; i < count; i++) {
-        #if POOL_USE_HEADERS
-        // Skip header space - user data starts after header
-        void* user_ptr = ptr + POOL_HEADER_SIZE;
-        #else
-        void* user_ptr = ptr;
-        #endif
+    for (int i = 0; i < carved; i++) {
+        void* block = blocks[i];
 
-        // Chain the blocks
+        // Chain the block
         if (!head) {
-            head = user_ptr;
-            tail = user_ptr;
+            head = block;
+            tail = block;
         } else {
-            *(void**)tail = user_ptr;
-            tail = user_ptr;
-        }
-
-        // Move to next block
-        ptr += total_block_size;
-
-        // Stop if we'd go past the allocated chunk
-        if ((ptr + total_block_size) > ((char*)chunk + total_size)) {
-            break;
+            *(void**)tail = block;
+            tail = block;
         }
     }
 
@@ -102,4 +95,4 @@ void* backend_batch_carve(int class_idx, int count) {
     }
 
     return head;
-}
+}