hakmem/core/box/smallobject_policy_v7_box.h

// smallobject_policy_v7_box.h - SmallObject Policy v7 (Phase v7-7: Learner integration)
//
// Purpose:
//   - Centralized routing policy for ULTRA / v7 / MID_v3 / LEGACY
//   - Single source of truth for class → route_kind mapping
//   - ENV configuration managed in one place (L3 Policy layer)
//   - Learner: dynamic route switching based on workload stats (v7-7)

#ifndef HAKMEM_SMALLOBJECT_POLICY_V7_BOX_H
#define HAKMEM_SMALLOBJECT_POLICY_V7_BOX_H

#include <stdint.h>
#include <stdbool.h>
#include "smallobject_learner_v7_box.h"  // For SmallLearnerStatsV7 type

// ============================================================================
// Route Kind Enum (L0/L1/L1' layer selection)
// ============================================================================

typedef enum {
    SMALL_ROUTE_ULTRA,      // L0: C4-C7 ULTRA (FROZEN)
    SMALL_ROUTE_V7,         // L1: SmallObject v7 (research box)
    SMALL_ROUTE_MID_V3,     // L1': MID v3 (257-768B mid/small)
    SMALL_ROUTE_MID_V35,    // L1': MID v3.5 (v11a-3: Segment/ColdIface/Stats/Learner v2)
    SMALL_ROUTE_LEGACY,     // L1': TinyHeap v1 / Pool v1 (fallback)
} SmallRouteKind;

// ============================================================================
// Policy Snapshot Structure
// ============================================================================

typedef struct SmallPolicyV7 {
    SmallRouteKind route_kind[8];  // C0-C7 routing decision
} SmallPolicyV7;

// ============================================================================
// Policy API
// ============================================================================

/// Get policy snapshot (read-only, TLS cached)
/// Frontend calls this to determine route_kind[class_idx]
const SmallPolicyV7* small_policy_v7_snapshot(void);

/// Initialize policy from ENV variables (called once at startup)
/// Priority: ULTRA > v7 > MID_v3 > LEGACY
/// @param policy: Policy structure to initialize
void small_policy_v7_init_from_env(SmallPolicyV7* policy);

/// Get route kind name for debugging
const char* small_route_kind_name(SmallRouteKind kind);

/// Update policy from Learner stats (called periodically)
/// Decision rule: if C5 alloc ratio > 30%, route C5 to v7, else MID_v3
/// @param stats: Learner stats to evaluate
/// @param policy_out: Policy to update
void small_policy_v7_update_from_learner(
    const SmallLearnerStatsV7* stats,
    SmallPolicyV7* policy_out
);

#endif // HAKMEM_SMALLOBJECT_POLICY_V7_BOX_H