// front_gate_classifier.h - Box FG: Pointer Classification Front Gate
//
// Purpose: Single point of truth for classifying pointers (Tiny/Pool/Mid/Large)
// Design: Heuristic-free, safe header probe + Registry lookup fallback
//
// Key Rules:
//   1. ptr-1 is read ONLY here (never elsewhere)
//   2. Header probe only when safe (same page + readable)
//   3. C7 (headerless) always identified via Registry
//   4. No 1KB alignment heuristics (eliminated false positives)
//
// Architecture:
//   - Box FG (this): Classification authority
//   - Box REG: SuperSlab registry (O(1) reverse lookup)
//   - Box TLS: next pointer clearing for C7
//
// Performance:
//   - Fast path (C0-C6 header): 5-10 cycles (unchanged)
//   - Slow path (C7 REG): 50-100 cycles (rare)
//   - Safety: SEGV eliminated, false positive = 0%

#ifndef FRONT_GATE_CLASSIFIER_H
#define FRONT_GATE_CLASSIFIER_H

#include <stdint.h>
#include <stddef.h>

// Forward declaration
struct SuperSlab;

// Pointer classification kinds
typedef enum {
    PTR_KIND_TINY_HEADER,      // C0-C6: Has 1-byte header (fast path)
    PTR_KIND_TINY_HEADERLESS,  // C7: Headerless 1KB blocks (REG path)
    PTR_KIND_POOL_TLS,         // Pool TLS 8KB-52KB
    PTR_KIND_MID_LARGE,        // Mid/Large allocations
    PTR_KIND_UNKNOWN           // Unknown/external allocation
} tiny_ptr_kind_t;

// Classification result
typedef struct {
    tiny_ptr_kind_t kind;      // Classification result
    int class_idx;             // Tiny class (0-7), or -1 if not Tiny
    struct SuperSlab* ss;      // SuperSlab pointer (from Registry, or NULL)
    int slab_idx;              // Slab index within SuperSlab (or -1)
} ptr_classification_t;

// ========== Front Gate API ==========

// Classify pointer (single point of truth)
// Returns: Classification result with kind, class_idx, SuperSlab
//
// Strategy:
//   1. Try safe header probe (C0-C6 fast path: 5-10 cycles)
//   2. Fallback to Registry lookup (C7 or header failed)
//   3. Check Pool TLS magic
//   4. Check AllocHeader (16-byte malloc/mmap)
//   5. Return UNKNOWN if all fail
//
// Safety:
//   - Header probe only if: (ptr & 0xFFF) >= 1 (same page)
//   - No 1KB alignment heuristics
//   - Registry provides ground truth for headerless
ptr_classification_t classify_ptr(void* ptr);

// ========== Debug/Stats (optional) ==========

#if !HAKMEM_BUILD_RELEASE
// Track classification hit rates
extern __thread uint64_t g_classify_header_hit;
extern __thread uint64_t g_classify_headerless_hit;
extern __thread uint64_t g_classify_pool_hit;
extern __thread uint64_t g_classify_mid_large_hit;
extern __thread uint64_t g_classify_unknown_hit;

void front_gate_print_stats(void);
#endif

#endif // FRONT_GATE_CLASSIFIER_H