// smallobject_learner_v7_box.h - SmallObject Learner v7 (Phase v7-7)
//
// Purpose:
//   - Dynamic workload-based route switching for C5
//   - Detects C5 allocation ratio via refill/retire events
//   - Routes C5 to v7 or MID_v3 based on observed traffic pattern
//
// Decision Rule:
//   - If C5 ratio >= 30%: route C5 to v7 (heavy C5 workload)
//   - If C5 ratio < 30%: route C5 to MID_v3 (mixed/light C5)
//
// Integration:
//   - ColdIface calls record_refill() and record_retire()
//   - Policy queries Learner stats periodically via update_from_learner()
//   - Version-based TLS cache invalidation ensures consistent routing
//

#ifndef HAKMEM_SMALLOBJECT_LEARNER_V7_BOX_H
#define HAKMEM_SMALLOBJECT_LEARNER_V7_BOX_H

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

// ============================================================================
// Learner Stats (Phase v7-7)
// ============================================================================

/// Per-class stats for Learner
typedef struct SmallLearnerClassStatsV7 {
    uint64_t total_allocs;      // Total allocs for this class (all routes)
    uint64_t v7_allocs;         // Allocs via v7 route
    uint64_t v7_retires;        // Page retires from v7
    uint32_t sample_count;      // Number of samples
} SmallLearnerClassStatsV7;

/// Aggregate Learner stats
typedef struct SmallLearnerStatsV7 {
    SmallLearnerClassStatsV7 per_class[8];  // C0-C7
    uint64_t total_retires;                  // Total page retires
    uint64_t eval_count;                     // Number of evaluations
} SmallLearnerStatsV7;

// ============================================================================
// Learner API (Phase v7-7)
// ============================================================================

/// Record a page retire for Learner stats (called from ColdIface)
/// @param class_idx: Size class of the retired page
/// @param capacity: Capacity of the page (used as traffic proxy)
void small_learner_v7_record_retire(uint32_t class_idx, uint64_t capacity);

/// Record a page refill for Learner stats (called from ColdIface)
/// @param class_idx: Size class of the refilled page
/// @param capacity: Capacity of the page (used as traffic proxy)
void small_learner_v7_record_refill(uint32_t class_idx, uint64_t capacity);

/// Get current Learner stats snapshot (for debugging/OBSERVE)
const SmallLearnerStatsV7* small_learner_v7_stats_snapshot(void);

/// Force re-evaluation of policy from current stats
/// Internal: called periodically to invalidate TLS policy cache
void small_learner_v7_evaluate(void);

// ============================================================================
// Learner Configuration
// ============================================================================

/// Learner threshold for C5 route decision (default: 30%)
#define SMALL_LEARNER_C5_THRESHOLD_PCT  30

/// Evaluation interval (every N refills)
#define SMALL_LEARNER_EVAL_INTERVAL     100

#endif // HAKMEM_SMALLOBJECT_LEARNER_V7_BOX_H