hakmem/core/hakmem_evo.h

// hakmem_evo.h - Learning Lifecycle State Machine
// Purpose: LEARN → FROZEN → CANARY state machine for ELO learning lifecycle
//
// License: MIT
// Date: 2025-10-21

#ifndef HAKMEM_EVO_H
#define HAKMEM_EVO_H

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

// ============================================================================
// Evolution Policy (Environment Variable: HAKMEM_EVO)
// ============================================================================

typedef enum {
    EVO_POLICY_AUTO,    // Auto state transitions (LEARN→FROZEN→CANARY)
    EVO_POLICY_LEARN,   // Force LEARN (for benchmarking)
    EVO_POLICY_FROZEN,  // Force FROZEN (for production testing)
    EVO_POLICY_OFF      // Disable learning (Phase 6.3 equivalent)
} hak_evo_policy_t;

// ============================================================================
// Evolution Mode (Current State)
// ============================================================================

typedef enum {
    EVO_MODE_LEARN,     // Learning (ELO updates enabled)
    EVO_MODE_FROZEN,    // Frozen (ELO updates disabled, use confirmed policy)
    EVO_MODE_CANARY     // Canary (試行: 5% sampling with candidate policy)
} hak_evo_mode_t;

// ============================================================================
// Configuration (Defaults + Environment Variables)
// ============================================================================

typedef struct {
    // Policy
    hak_evo_policy_t policy;

    // Freeze conditions
    uint64_t freeze_time_sec;       // T_freeze (default: 180s)
    double   freeze_epsilon;        // ε (default: 0.01 = 1%)
    int      freeze_window_count;   // W (default: 3 windows)

    // Re-learning triggers
    double   relearn_delta;         // δ (default: 0.20 = 20% degradation)
    int      relearn_L_windows;     // L (default: 3 consecutive windows)
    double   dist_delta;            // Δ (default: 0.25 = distribution change)

    // Window configuration
    uint64_t window_ops;            // Operations per window (default: 10000)
    uint64_t window_sec;            // Seconds per window (default: 2)

    // CANARY configuration
    double   canary_frac;           // ε_canary (default: 0.05 = 5%)
    uint64_t canary_timeout_sec;    // Timeout (default: 60s)

    // Cooldown
    uint64_t cooldown_sec;          // C (default: 30s)
} hak_evo_config_t;

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

// Initialize evolution state machine
void hak_evo_init(void);

// Shutdown and print statistics
void hak_evo_shutdown(void);

// Tick: Called periodically to check window closure and state transitions
// Returns: 1 if state changed, 0 otherwise
int hak_evo_tick(uint64_t now_ns);

// Record a latency sample (for P² p99 estimation)
void hak_evo_record_latency(double latency_ns);

// Record an allocation size (for distribution signature)
void hak_evo_record_size(size_t size);

// Get current evolution mode
hak_evo_mode_t hak_evo_get_mode(void);

// Check if currently frozen (ELO updates should be skipped)
int hak_evo_is_frozen(void);

// Check if currently in CANARY mode (for 5% sampling)
int hak_evo_is_canary(void);

// Get current p99 estimate
double hak_evo_get_p99(void);

// Manual mode override (for testing)
void hak_evo_force_mode(hak_evo_mode_t mode);

// Get config (for debugging)
const hak_evo_config_t* hak_evo_get_config(void);

// Print statistics
void hak_evo_print_stats(void);

// ============================================================================
// CANARY Mode Support (Phase 6.5 Step 5)
// ============================================================================

// Get confirmed best strategy (for FROZEN/CANARY 95%)
int hak_evo_get_confirmed_strategy(void);

// Get candidate strategy (for CANARY 5% trial)
int hak_evo_get_candidate_strategy(void);

// Check if should use candidate (5% sampling in CANARY mode)
// Returns 1 if candidate should be used, 0 for confirmed strategy
int hak_evo_should_use_candidate(void);

// Record CANARY trial result (for Go/No-Go decision)
void hak_evo_record_canary_result(int strategy_id, double latency_ns);

#endif // HAKMEM_EVO_H