hakmem/core/hakmem_site_rules.h

// hakmem_site_rules.h - Site-Aware Cache Routing (Phase 6.10.1 MVP)
// Purpose: O(1) call-site → cache route direct mapping
//
// Design Philosophy:
// - **Top-K only**: Track top 100 hot sites (32KB memory)
// - **4-probe hash**: O(1) lookup with collision handling
// - **Route types**: L2_POOL / BIGCACHE / MALLOC / MMAP
// - **TTL**: Auto-expire unused rules (30 min)
// - **Adoption gate**: Only apply rules with win_rate >= 60%
//
// License: MIT
// Date: 2025-10-21

#ifndef HAKMEM_SITE_RULES_H
#define HAKMEM_SITE_RULES_H

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

// ===========================================================================
// Configuration Constants
// ===========================================================================

#define SITE_RULES_CAPACITY 2048  // 4-probe hash table size (power of 2)
#define SITE_RULES_TOP_K 100      // Track top 100 hot sites only
#define SITE_RULES_TTL_SEC 1800   // 30 minutes (auto-expire)
#define SITE_RULES_MIN_WIN_RATE 0.6f  // Adoption gate: 60% win rate

// ===========================================================================
// Route Types
// ===========================================================================

typedef enum {
    ROUTE_NONE = 0,        // No rule (fallback to default logic)
    ROUTE_L2_POOL,         // Route to L2 Pool (2-32KB, site-based sharding)
    ROUTE_L25_POOL,        // Route to L2.5 Pool (64KB-1MB, page-granular)
    ROUTE_BIGCACHE,        // Route to BigCache (>= 1MB, size-class cache)
    ROUTE_MALLOC,          // Route to malloc (< threshold, fast path)
    ROUTE_MMAP             // Route to mmap (>= threshold, batch-friendly)
} RouteType;

// ===========================================================================
// Site Rule Entry (64 bytes, cache-line aligned)
// ===========================================================================

typedef struct __attribute__((aligned(64))) {
    uintptr_t site_id;     // Call-site address (0 = empty slot)
    uint8_t size_class;    // Size class (0-4 for 2KB/4KB/8KB/16KB/32KB)
    RouteType route;       // Routing decision (enum = 4 bytes)

    // Statistics (for adoption gate)
    uint32_t hit_count;    // Number of times this rule was applied
    uint32_t win_count;    // Number of times route was successful

    // TTL (time-to-live)
    uint64_t last_used_ns; // Last access time (for expiration)

    // Padding to 64 bytes: uintptr_t(8) + uint8_t(1) + RouteType(4) + 2*uint32_t(8) + uint64_t(8) = 29 bytes
    // Need 64 - 29 = 35 bytes padding
    uint8_t _padding[35];
} SiteRule;

// ===========================================================================
// Public API
// ===========================================================================

// Initialize Site Rules system
void hak_site_rules_init(void);

// Shutdown Site Rules system
void hak_site_rules_shutdown(void);

// Lookup Site Rule (O(1) 4-probe hash table)
// Args: site_id - call-site address
//       size - allocation size (for size class determination)
// Returns: RouteType (ROUTE_NONE if no rule found or expired)
RouteType hak_site_rules_lookup(uintptr_t site_id, size_t size);

// Manually add a Site Rule (for MVP testing)
// Args: site_id - call-site address
//       size - allocation size (for size class)
//       route - routing decision
// Returns: 1 on success, 0 on failure (table full)
int hak_site_rules_add(uintptr_t site_id, size_t size, RouteType route);

// Print Site Rules statistics
void hak_site_rules_print_stats(void);

// ===========================================================================
// Internal Helpers (for testing/debugging)
// ===========================================================================

// Get size class from size (0-4 for 2KB/4KB/8KB/16KB/32KB, 255 = out of range)
uint8_t hak_site_rules_get_size_class(size_t size);

// Check if Site Rule should be applied (adoption gate: win_rate >= 60%)
int hak_site_rules_should_apply(SiteRule* rule);

#endif // HAKMEM_SITE_RULES_H