// Phase 2 方案B：真实区槽状态 C++ 全接管（1 次同步版）+ demand_dual。
// 复刻 Python ResidentExpertPool 的 free/LFU 语义，成为 dual-source decode 真实区唯一权威。
#pragma once
#include "../common.h"

void real_init(int layer, int cap);                       // 初始化某层真实区(cap 槽全空闲)，幂等
std::vector<int> real_region_contents(int layer);         // [expert, slot, ...]
int real_region_count(int layer);
void real_reset();
// AUTOPIN：注册 pinned 热专家(驱逐免选)，返回平行槽位(-1=分不到)；前置 real_init。
std::vector<int> real_pin(int layer, const std::vector<int>& experts);
// 该层 pinned(永不可驱逐)专家数。调用方据此算「可安放的唯一专家上限」= cap − pinned，
// 用于在超容量前把该前向分流到 host/fetch 路径（超了会落 0 号槽 → 逐位错算）。
int real_pinned_count(int layer);
// AUTOPIN：导出各层 LFU 累计频次，扁平 [layer, expert, count, ...]。
std::vector<long> real_freq_dump();
// demand 全接管：inds 惰性(内部 eval 一次)；side_gen 侧区代；pool_list 为 _segs 顺序池数组。
mx::array demand_dual(
    const mx::array& inds, const std::vector<mx::array>& pool_list,
    const std::vector<int>& seg_nbytes, int layer, int side_gen, const std::string& path,
    int stride, int cap, bool lfu, int decay_interval, mx::StreamOrDevice s);
// [hitpos, misspos, loads, fallback01, unplaced]
// unplaced：本次分不到槽、被迫落 0 号槽的唯一专家数。>0 即该前向逐位错算(必须为 0)。
std::vector<long> demand_last_stats();
std::vector<double> demand_timings();                     // [inds_eval, pool_eval, state, build] us
void demand_timing_enable(bool on);
// 测试壳：纯状态推进(不 pread/不侧区)，返回 local 槽位；供 LFU 驱逐等价对拍。
std::vector<int> real_debug_place(int layer, const std::vector<int>& experts_flat, int cap,
                                  bool lfu, int decay_interval);