hakmem/core/box/smallobject_policy_v2_box.h

// smallobject_policy_v2_box.h
// Phase v11a: Policy Box v2 with extended Learner integration

#ifndef SMALLOBJECT_POLICY_V2_BOX_H
#define SMALLOBJECT_POLICY_V2_BOX_H

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// Route Kinds (Shared with Policy v1)
// ============================================================================

typedef enum {
    SMALL_ROUTE_ULTRA = 0,    // ULTRA fast path (C4-C7)
    SMALL_ROUTE_V7 = 1,       // SmallObject v7 research box (C5/C6)
    SMALL_ROUTE_MID_V3 = 2,   // MID v3.5 main box (C5-C7)
    SMALL_ROUTE_LEGACY = 3,   // Legacy fallback (all classes)
} SmallRouteKind;

// ============================================================================
// Policy State (Extended from v1)
// ============================================================================

/**
 * SmallPolicyV2: Routing decision table with version tracking
 *
 * Extends SmallPolicyV7 with:
 * - Version-based TLS invalidation (atomic updates)
 * - Integration point for Learner v2
 * - Support for multi-class MID v3.5
 */
typedef struct {
    uint8_t route_kind[8];              // Route per class index (C0-C7)
    uint32_t policy_version;            // Version for TLS cache invalidation
    uint64_t last_update_timestamp_ms;  // When policy was last updated
    uint32_t learner_eval_count;        // How many times learner updated this
    uint8_t reserved[32];               // For future extensions
} SmallPolicyV2;

// ============================================================================
// Policy Lifecycle
// ============================================================================

/**
 * Get thread-local policy snapshot
 * This is the main entry point for routing decisions
 *
 * Policy snapshot is cached in TLS:
 * - If version matches global version: return cached snapshot
 * - Otherwise: re-initialize from ENV and apply Learner updates
 *
 * Returns pointer to TLS-local SmallPolicyV2 (valid until next call)
 */
const SmallPolicyV2* small_policy_v2_snapshot(void);

/**
 * Initialize policy from environment variables
 * Called on first access or when version mismatch detected
 *
 * Reads ENV:
 *   HAKMEM_TINY_C7_ULTRA_ENABLED        → route[7] = ULTRA
 *   HAKMEM_SMALL_HEAP_V7_ENABLED        → route[5/6] = V7
 *   HAKMEM_SMALL_HEAP_V7_CLASSES        → which classes for v7
 *   HAKMEM_MID_V3_ENABLED               → route[5/6/7] = MID_V3
 *   HAKMEM_MID_V3_CLASSES               → which classes for MID_v3
 */
void small_policy_v2_init_from_env(SmallPolicyV2 *policy);

// ============================================================================
// Learner Integration
// ============================================================================

/**
 * Update policy based on learner statistics
 * Called when learner detects workload change (route switch opportunity)
 *
 * Decision logic (Phase v11a):
 * - C5 ratio >= threshold AND v7 available → route[5] = V7
 * - C5 ratio <  threshold              → route[5] = MID_V3
 *
 * May be extended (Phase v11b) for multi-dimensional decisions:
 * - retire_efficiency, free_hit_ratio, fragmentation, etc.
 */
void small_policy_v2_update_from_learner(
    const SmallLearnerStatsV2 *stats,
    SmallPolicyV2 *policy_out
);

/**
 * Called by learner after route decision
 * Invalidates TLS policy caches so next access gets updated policy
 */
void small_policy_v2_invalidate_tls_cache(void);

// ============================================================================
// Route Accessors
// ============================================================================

/**
 * Get route for class index
 * Returns SmallRouteKind for class_idx (C0-C7)
 */
SmallRouteKind small_policy_v2_get_route(uint32_t class_idx);

/**
 * Get route name string (for debugging/logging)
 */
const char* small_policy_v2_route_name(SmallRouteKind route);

/**
 * Check if class is supported by specific route
 */
bool small_policy_v2_route_supports_class(SmallRouteKind route,
                                          uint32_t class_idx);

// ============================================================================
// Configuration & Control
// ============================================================================

/**
 * Set global policy version
 * Called by learner to trigger TLS cache invalidation
 * Internal API
 */
void small_policy_v2_set_version(uint32_t version);

/**
 * Get current policy version
 */
uint32_t small_policy_v2_get_version(void);

/**
 * Check if TLS policy cache is stale
 * (version != global version)
 */
bool small_policy_v2_tls_cache_stale(void);

/**
 * Force policy re-evaluation
 * Useful for ENV variable changes at runtime
 */
void small_policy_v2_reload_from_env(void);

// ============================================================================
// Debugging & Monitoring
// ============================================================================

/**
 * Print current policy routing table
 * Shows which route each class is assigned to
 */
void small_policy_v2_print_routing(void);

/**
 * Print policy history
 * Shows recent policy changes (for learner effectiveness monitoring)
 */
void small_policy_v2_print_history(void);

/**
 * Get policy statistics
 */
typedef struct {
    uint32_t total_route_switches;
    uint32_t learner_driven_switches;
    uint32_t env_driven_reloads;
    uint64_t last_switch_timestamp_ms;
    char last_switch_description[128];
} SmallPolicyStats_V2;

SmallPolicyStats_V2 small_policy_v2_get_stats(void);

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

#ifndef SMALL_ROUTE_PRIORITY_NONE
// Priority order (highest to lowest):
//   1. ULTRA (if enabled for class)
//   2. V7 (if enabled and Learner decides)
//   3. MID_V3 (if enabled, usually default)
//   4. LEGACY (fallback for all classes)
#define SMALL_ROUTE_PRIORITY_NONE 0
#endif

// ============================================================================
// Backward Compatibility
// ============================================================================

// For code that uses v1 types:
// typedef SmallPolicyV2 SmallPolicyV7;  // Can be added if needed

// Old function names can be aliased:
// #define small_policy_v7_snapshot() small_policy_v2_snapshot()
// etc.

#ifdef __cplusplus
}
#endif

#endif // SMALLOBJECT_POLICY_V2_BOX_H