entropic.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include "engine_handle.h"
 
#include <entropic/config/loader.h>
#include <entropic/config/validate.h>  // gh#154: configure-time grammar check
#include <entropic/mcp/servers/entropic_server.h>
#include <entropic/entropic.h>
#include <entropic/prompts/manager.h>
#include <entropic/types/logging.h>
#include "llama_cpp_backend.h"
#include <entropic/inference/interface_factory.h>
#include <entropic/inference/orchestrator.h>
#include <entropic/interfaces/i_inference_backend.h>
#include <entropic/types/messages_json.h>
#include "json_serializers.h"
#include "utf8_safe.h"
#include "../inference/tool_call_serialize.h"  // gh#98: shared typed serializer
 
#include <nlohmann/json.hpp>
 
#include <atomic>
 
#include <cstdlib>
#include <fstream>
#include <vector>
#include <cstring>
#include <filesystem>
#include <new>
#include <stdexcept>
#include <string>
 
static auto s_log = entropic::log::get("facade");
 
template <typename Fn>
static entropic_error_t c_api_try(entropic_handle_t handle, Fn&& fn) {
    entropic_error_t rc = ENTROPIC_ERROR_INTERNAL;
    try {
        rc = fn();
    } catch (const std::filesystem::filesystem_error& e) {
        if (handle) { handle->last_error = e.what(); }
        s_log->error("c_api filesystem_error: {}", e.what());
        rc = ENTROPIC_ERROR_IO;
    } catch (const nlohmann::json::exception& e) {
        if (handle) { handle->last_error = e.what(); }
        s_log->error("c_api json::exception: {}", e.what());
        rc = ENTROPIC_ERROR_INVALID_CONFIG;
    } catch (const std::exception& e) {
        if (handle) { handle->last_error = e.what(); }
        s_log->error("c_api std::exception: {}", e.what());
        rc = ENTROPIC_ERROR_INTERNAL;
    }
    return rc;
}
 
static char* alloc_cstr(const char* src) {
    if (!src) { return nullptr; }
    size_t len = std::strlen(src) + 1;
    auto* dst = static_cast<char*>(entropic_alloc(len));
    if (dst) { std::memcpy(dst, src, len); }
    return dst;
}
 
static char* alloc_cstr(const std::string& src) {
    return alloc_cstr(src.c_str());
}
 
/* setup_ggml_logging moved to ModelOrchestrator::initialize() — Step 7 */
 
// gh#58 follow-up (v2.2.6): per-handle last_error. Pre-v2.2.6 the
// public API in src/types/error.cpp ignored the handle parameter and
// returned a single thread-local buffer, so every handle->last_error
// assignment in the facade was unreadable from the consumer side.
// Thread-local cache here means the returned const char* stays valid
// until the *same* thread calls entropic_last_error again — matching
// the documented v1.8.0 contract.
static thread_local std::string s_last_error_cache;
static thread_local char s_pre_create_error[512] = "";
 
extern "C" const char* entropic_last_error(entropic_handle_t handle) {
    if (!handle) { return s_pre_create_error; }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    s_last_error_cache = handle->last_error;
    return s_last_error_cache.c_str();
}
 
static entropic_error_t check_orchestrator(entropic_handle_t h) {
    if (!h) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!h->configured.load() || !h->orchestrator) {
        return ENTROPIC_ERROR_INVALID_STATE;
    }
    return ENTROPIC_OK;
}
 
static entropic_error_t check_mcp_auth(entropic_handle_t h) {
    if (!h) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!h->configured.load() || !h->mcp_auth) {
        return ENTROPIC_ERROR_INVALID_STATE;
    }
    return ENTROPIC_OK;
}
 
static entropic_error_t check_identity(entropic_handle_t h) {
    if (!h) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!h->configured.load() || !h->identity_manager) {
        return ENTROPIC_ERROR_INVALID_STATE;
    }
    return ENTROPIC_OK;
}
 
/* find_tier_by_model_path moved to ModelsConfig::find_tier_by_path() — v2.0.1 */
 
static entropic::InferenceBackend* require_ready_backend(
    entropic_handle_t h, const char* tier_name)
{
    const std::string tier(tier_name);
    if (h->orchestrator->get_backend(tier) == nullptr) {
        throw std::runtime_error("no backend for tier: " + tier);
    }
    auto* backend = h->orchestrator->ensure_model(tier);
    if (backend == nullptr || !backend->is_active()) {
        throw std::runtime_error(
            "model could not be made resident for tier: " + tier);
    }
    return backend;
}
 
extern "C" {
 
entropic_error_t entropic_create(entropic_handle_t* handle) {
    if (handle == nullptr) {
        return ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    entropic::log::init(spdlog::level::info);
    entropic_inference_log_silence();  // silent until configure enables
 
    auto* engine = new (std::nothrow) entropic_engine();
    if (engine == nullptr) {
        *handle = nullptr;
        return ENTROPIC_ERROR_OUT_OF_MEMORY;
    }
 
    // gh#59 (v2.3.1): assign a monotonic log id. Used by the
    // HandleAwareSink dispatcher to route session.log writes to the
    // right file when multiple handles coexist. 0 is reserved for
    // "no handle scope active."
    static std::atomic<int> s_log_id_counter{0};
    engine->log_id = ++s_log_id_counter;
 
    s_log->info("entropic_create() — v{} (log_id={})",
                CONFIG_ENTROPIC_VERSION_STRING, engine->log_id);
 
    *handle = engine;
    return ENTROPIC_OK;
}
 
/* preload_bundled_models moved to BundledModels::auto_discover_and_load() — Step 6 */
 
/* InferenceInterface wiring moved to inference/interface_factory.cpp — Step 3 */
 
/* InferenceInterface C-wrappers + factory moved to inference/interface_factory.cpp — Step 3 */
 
/* facade_process_directives → engine->build_directive_hooks() — v2.0.2 */
/* facade_resolve_tier/tier_exists/handoff/param → engine->set_tier_info() — v2.0.2 */
/* wire_engine_interfaces → inline in configure_common — v2.0.2 */
 
// ── Tool prompt injection (v2.0.4) ─────────────────────────
 
static std::vector<std::string> resolve_allowed_tools(
    entropic_engine* h, const std::string& tier) {
    // Primary: cached from identity frontmatter (v2.0.4)
    auto cached = h->tier_allowed_tools.find(tier);
    if (cached != h->tier_allowed_tools.end()) {
        return cached->second;
    }
    // Fallback: dynamic identity or model config
    if (h->identity_manager) {
        auto* cfg = h->identity_manager->get(tier);
        if (cfg && !cfg->allowed_tools.empty()) {
            return cfg->allowed_tools;
        }
    }
    return {};
}
 
static std::vector<std::string> filter_tools(
    const nlohmann::json& all_tools,
    const std::vector<std::string>& allowed) {
    std::vector<std::string> result;
    for (const auto& tool : all_tools) {
        std::string name = tool.value("name", "");
        bool pass = allowed.empty()
            || std::find(allowed.begin(), allowed.end(), name)
               != allowed.end();
        if (pass) { result.push_back(tool.dump()); }
    }
    return result;
}
 
static std::string tool_defs_array(
    const std::vector<std::string>& tool_jsons) {
    nlohmann::json arr = nlohmann::json::array();
    for (const auto& tj : tool_jsons) {
        auto obj = nlohmann::json::parse(tj, nullptr, false);
        if (!obj.is_discarded()) { arr.push_back(std::move(obj)); }
    }
    return arr.dump();
}
 
static int facade_get_tool_prompt(const char* tier, char** result,
                                  void* user_data) {
    auto* h = static_cast<entropic_engine*>(user_data);
    *result = nullptr;
    // gh#166: the tools a turn sees belong to the SESSION's workspace. The
    // key arrives through `entropic::current_run_session()` because this
    // callback's signature lives in an interface header.
    auto* servers = (h != nullptr && h->server_manager)
        ? entropic::workspace_servers(h, entropic::current_run_session())
        : nullptr;
    if (servers == nullptr) { return 1; }
    auto all_tools = nlohmann::json::parse(servers->list_tools(),
                                           nullptr, false);
    auto tool_jsons = filter_tools(
        all_tools, resolve_allowed_tools(h, tier ? tier : ""));
    if (!all_tools.is_array() || all_tools.empty() || tool_jsons.empty()) {
        return 1;
    }
    *result = strdup(tool_defs_array(tool_jsons).c_str());
    return 0;
}
 
 
static void wire_external_interrupt(entropic_handle_t h) {
    h->engine->set_external_interrupt(
        [](void* ud) {
            auto* sm = static_cast<entropic::ServerManager*>(ud);
            if (sm) { sm->interrupt_external_tools(); }
        }, h->server_manager.get());
    // gh#150: wire the release alongside the abort, never separately. A
    // handle that can interrupt its transports but not un-interrupt them
    // is the defect itself, so the two are registered together and any
    // future call site gets both or neither.
    h->engine->set_external_reset(
        [](void* ud) {
            auto* sm = static_cast<entropic::ServerManager*>(ud);
            if (sm) { sm->clear_external_tool_interrupts(); }
        }, h->server_manager.get());
}
 
static void rewire_stream_observer(entropic_handle_t h) {
    if (h->stream_observer != nullptr && h->engine) {
        h->engine->set_stream_observer(
            h->stream_observer, h->stream_observer_data);
    }
}
 
static void rewire_queue_observer(entropic_handle_t h) {
    if (h->queue_observer != nullptr && h->engine) {
        h->engine->set_queue_observer(
            h->queue_observer, h->queue_observer_data);
    }
}
 
static void rewire_state_observer(entropic_handle_t h) {
    if (h->state_observer != nullptr && h->engine) {
        h->engine->set_state_observer(
            h->state_observer, h->state_observer_data);
    }
}
 
static void rewire_critique_callbacks(entropic_handle_t h) {
    if ((h->critique_start_cb != nullptr || h->critique_end_cb != nullptr)
            && h->validator) {
        h->validator->set_critique_callbacks(
            h->critique_start_cb,
            h->critique_end_cb,
            h->critique_cb_data);
    }
}
 
static void rewire_observers(entropic_handle_t h) {
    rewire_stream_observer(h);
    rewire_queue_observer(h);
    rewire_critique_callbacks(h);
    rewire_state_observer(h);
}
 
static void populate_tier_info(entropic_handle_t h,
                               const std::filesystem::path& data_dir,
                               const std::string& shared_prefix) {
    for (const auto& [name, tier] : h->config.models.tiers) {
        entropic::ChildContextInfo info;
        info.valid = true;
        auto parsed = entropic::prompts::resolve_tier_identity_full(
            tier, name, data_dir);
        info.system_prompt = shared_prefix + parsed.body;
        info.explicit_completion = parsed.frontmatter.explicit_completion
            .value_or(!tier.auto_chain.has_value());
        // E6 (2.0.6-rc18): propagate per-identity caps from frontmatter
        // so AgentEngine::tri_get_tier_param surfaces them to the loop
        // and tool executor. -1 = "use global loop_config default".
        info.max_iterations_override =
            parsed.frontmatter.max_iterations;
        info.max_tool_calls_per_turn_override =
            parsed.frontmatter.max_tool_calls_per_turn;
        info.max_consecutive_empty_turns_override =
            parsed.frontmatter.max_consecutive_empty_turns;
        info.allowed_tools = resolve_allowed_tools(h, name);  // gh#121
        h->engine->set_tier_info(name, info);
    }
}
 
// ── configure_common ───────────────────────────────────────
 
static bool si_create_delegation(
        const char* parent_id, const char* delegating_tier,
        const char* target_tier, const char* task, int max_turns,
        std::string& delegation_id, std::string& child_conversation_id,
        void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    if (sb == nullptr) { return false; }
    return sb->create_delegation(
        parent_id ? parent_id : "",
        delegating_tier ? delegating_tier : "",
        target_tier ? target_tier : "",
        task ? task : "",
        max_turns, delegation_id, child_conversation_id);
}
 
static bool si_create_conversation(
        const char* title, std::string& conversation_id,
        void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    if (sb == nullptr) { return false; }
    conversation_id = sb->create_conversation(
        title ? title : "session", std::nullopt, std::nullopt);
    return !conversation_id.empty();
}
 
static bool si_complete_delegation(
        const char* delegation_id, const char* status,
        const char* summary, void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    if (sb == nullptr || delegation_id == nullptr) { return false; }
    std::optional<std::string> sum;
    if (summary != nullptr) { sum = summary; }
    return sb->complete_delegation(delegation_id,
                                   status ? status : "completed", sum);
}
 
static bool si_save_conversation(
        const char* conversation_id, const char* messages_json,
        void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    if (sb == nullptr || conversation_id == nullptr
        || messages_json == nullptr) {
        return false;
    }
    return sb->save_messages(conversation_id, messages_json);
}
 
static bool si_save_snapshot(
        const char* conversation_id, const char* messages_json,
        void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    if (sb == nullptr || conversation_id == nullptr
        || messages_json == nullptr) {
        return false;
    }
    return sb->save_snapshot(conversation_id, messages_json);
}
 
static bool si_latest_delegation_for_target(
        const char* target_tier, std::string& delegation_id,
        void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    if (sb == nullptr || target_tier == nullptr) { return false; }
    return sb->latest_delegation_for_target(target_tier, delegation_id);
}
 
static bool si_load_delegation_with_messages(
        const char* delegation_id, std::string& result_json,
        void* user_data) {
    auto* sb = static_cast<entropic::SqliteStorageBackend*>(user_data);
    bool ok = sb != nullptr && delegation_id != nullptr;
    std::string del_json;
    nlohmann::json del, conv;
    std::string child_id, target, conv_json;
    if (ok) {
        ok = sb->get_delegation_by_id(delegation_id, del_json);
    }
    if (ok) {
        del = nlohmann::json::parse(del_json, nullptr, false);
        ok = del.is_object();
    }
    if (ok) {
        child_id = del.value("child_conversation_id", std::string{});
        target = del.value("target_tier", std::string{});
        ok = !child_id.empty() && !target.empty()
             && sb->load_conversation(child_id, conv_json);
    }
    if (ok) {
        conv = nlohmann::json::parse(conv_json, nullptr, false);
        ok = conv.is_object();
    }
    if (ok) {
        conv["target_tier"] = target;
        conv["delegation_id"] = del.value("id", std::string{});
        result_json = conv.dump();
    }
    return ok;
}
 
static entropic::StorageInterface build_storage_iface(
        entropic::SqliteStorageBackend* sb) {
    entropic::StorageInterface si{};
    si.create_conversation = si_create_conversation;
    si.create_delegation = si_create_delegation;
    si.complete_delegation = si_complete_delegation;
    si.save_conversation = si_save_conversation;
    si.save_snapshot = si_save_snapshot;
    si.load_delegation_with_messages = si_load_delegation_with_messages;
    si.latest_delegation_for_target = si_latest_delegation_for_target;
    si.user_data = sb;
    return si;
}
 
static void init_persistence(entropic_handle_t h) {
    if (h->config.log_dir.empty()) { return; }
    auto db_path = h->config.log_dir / "entropic.db";
    h->storage = std::make_unique<entropic::SqliteStorageBackend>(db_path);
    if (h->storage->initialize()) {
        s_log->info("storage: {}", db_path.string());
    } else {
        s_log->warn("storage init failed, continuing without persistence");
        h->storage.reset();
    }
    // gh#32 (v2.1.6): wire StorageInterface into the engine so the
    // create_delegation/save_conversation paths actually persist (they
    // were dead code pre-2.1.6 because nothing populated the iface).
    if (h->storage && h->engine) {
        h->engine->set_storage(build_storage_iface(h->storage.get()));
    }
    h->session_logger = std::make_unique<entropic::SessionLogger>(
        h->config.log_dir);
}
 
static std::vector<std::string> collect_delegatable_tiers(
    const entropic::ParsedConfig& config) {
    std::unordered_set<std::string> targets;
    for (const auto& [source, dests] : config.routing.handoff_rules) {
        for (const auto& t : dests) { targets.insert(t); }
    }
    if (targets.empty()) {
        for (const auto& [name, tier] : config.models.tiers) {
            if (name != config.models.default_tier) {
                targets.insert(name);
            }
        }
    }
    return {targets.begin(), targets.end()};
}
 
static void init_mcp_servers(entropic_handle_t h,
                             const std::filesystem::path& data_dir) {
    auto root = h->config.mcp.working_dir.empty()
        ? std::filesystem::current_path()
        : std::filesystem::path(h->config.mcp.working_dir);
    h->server_manager = std::make_unique<entropic::ServerManager>(
        h->config.permissions, root);
    auto tier_names = collect_delegatable_tiers(h->config);
    // gh#162 (v2.13.0): tiers that refuse a contextless delegation, so the
    // delegate/pipeline tools can say no at the boundary.
    std::vector<std::string> require_context;
    for (const auto& [name, tier] : h->config.models.tiers) {
        if (tier.requires_context) { require_context.push_back(name); }
    }
    h->server_manager->init_builtins(
        h->config.mcp, tier_names, data_dir.string(), require_context);
    // v2.13.0: under `allow_outside_root: optional` the DEFAULT set asks
    // the host's path approver. Workspaces are built elsewhere and never
    // reach this line — they stay hard-confined (gh#166).
    entropic::wire_outside_root_approver(h);
 
    // gh#133 (v2.10.1): load dlopen plugins after the builtins so a plugin
    // colliding with a built-in server name is rejected rather than shadowing
    // it. Failures are already logged per-path with a typed code; startup
    // continues so the rest of the engine stays usable and the operator sees
    // the whole diagnosis at once.
    h->server_manager->load_plugins(h->config.mcp);
 
    // v2.14.0: the default set connects external servers too — declared ones
    // (mcp.external_servers, dead since v1.8.7: nothing called initialize()
    // here) and enabled .mcp.json ones, behind the same gate as a workspace.
    entropic::wire_external_server_policy(h, *h->server_manager, true);
    h->server_manager->initialize();
}
 
static std::string build_shared_prompt_prefix(
    entropic_handle_t h,
    const std::filesystem::path& data_dir) {
    std::string constitution, app_ctx;
    // gh#156: was two discarded error strings; the shared loader logs them.
    entropic::prompts::load_shared_prompt_sources(
        h->config, data_dir, constitution, app_ctx);
    std::string prefix;
    if (!constitution.empty()) { prefix += constitution + "\n\n"; }
    if (!app_ctx.empty()) { prefix += app_ctx + "\n\n"; }
    return prefix;
}
 
static void thread_frontmatter_sampler(
    entropic::TierConfig& tc,
    const entropic::prompts::IdentityFrontmatter& fm) {
    // gh#95 (v2.7.4): thread the identity `grammar:` key so the orchestrator's
    // resolve_grammar_key() finds it and constrains the tier's generation.
    // Without this the field is parsed but dropped here — registers OK, never
    // enforces (same class as the gh#82/85/94 sampler-threading gaps).
    if (fm.grammar.has_value()) {
        tc.grammar = std::filesystem::path(*fm.grammar);
    }
    if (fm.temperature.has_value()) { tc.temperature = *fm.temperature; }
    if (fm.max_output_tokens.has_value()) {
        tc.max_output_tokens = *fm.max_output_tokens;
    }
    if (fm.top_p.has_value()) { tc.top_p = *fm.top_p; }
    if (fm.top_k.has_value()) { tc.top_k = *fm.top_k; }
    if (fm.min_p.has_value()) { tc.min_p = *fm.min_p; }
    if (fm.presence_penalty.has_value()) {
        tc.presence_penalty = *fm.presence_penalty;
    }
    if (fm.frequency_penalty.has_value()) {
        tc.frequency_penalty = *fm.frequency_penalty;
    }
    // gh#86 (v2.5.4): repeat_penalty + enable_thinking.
    if (fm.repeat_penalty.has_value()) { tc.repeat_penalty = *fm.repeat_penalty; }
    if (fm.enable_thinking.has_value()) {
        tc.enable_thinking = *fm.enable_thinking;
    }
}
 
static void apply_identity_frontmatter(
    entropic_handle_t h,
    const std::string& name,
    const entropic::prompts::IdentityFrontmatter& fm) {
    if (fm.allowed_tools.has_value()) {
        h->tier_allowed_tools[name] = *fm.allowed_tools;
    }
    if (!fm.validation_rules.empty()) {
        h->tier_validation_rules[name] = fm.validation_rules;
    }
    if (fm.relay_single_delegate) {
        h->engine->set_relay_single_delegate(name);
    }
    // gh#94 (v2.7.3): per-tier frontmatter SAMPLERS are threaded earlier, in
    // thread_frontmatter_samplers() BEFORE init_orchestrator, so they land in
    // the orchestrator's by-value config snapshot. Threading them HERE (after
    // the snapshot) was the gh#94 ordering bug — the values reached h->config
    // but never the orchestrator's frozen copy, so tiers ran defaults.
}
 
static void cache_tier_allowed_tools(
    entropic_handle_t h,
    const std::filesystem::path& data_dir) {
    for (const auto& [name, tier] : h->config.models.tiers) {
        std::filesystem::path id_path;
        if (tier.identity.has_value()) {
            id_path = tier.identity.value();
        } else if (!tier.identity_disabled) {
            id_path = data_dir / "prompts" / ("identity_" + name + ".md");
        }
        if (id_path.empty() || !std::filesystem::exists(id_path)) {
            continue;
        }
        entropic::prompts::ParsedIdentity id;
        if (entropic::prompts::load_identity(id_path, id).empty()) {
            apply_identity_frontmatter(h, name, id.frontmatter);
        }
    }
    // gh#83 (v2.5.2): hand the populated allowlist map to the executor
    // for dispatch-time enforcement. A pointer to the handle-owned map
    // keeps this order-independent vs wire_tool_executor.
    if (h->tool_executor) {
        h->tool_executor->set_tier_allowed_tools(&h->tier_allowed_tools);
    }
}
 
static void thread_frontmatter_samplers(
    entropic_handle_t h,
    const std::filesystem::path& data_dir) {
    for (auto& [name, tier] : h->config.models.tiers) {
        std::filesystem::path id_path;
        if (tier.identity.has_value()) {
            id_path = tier.identity.value();
        } else if (!tier.identity_disabled) {
            id_path = data_dir / "prompts" / ("identity_" + name + ".md");
        }
        if (id_path.empty() || !std::filesystem::exists(id_path)) {
            continue;
        }
        entropic::prompts::ParsedIdentity id;
        if (entropic::prompts::load_identity(id_path, id).empty()) {
            thread_frontmatter_sampler(tier, id.frontmatter);
        }
    }
}
 
static char* tool_history_json_thunk(size_t count, void* ud) {
    auto* exec = static_cast<entropic::ToolExecutor*>(ud);
    if (exec == nullptr) { return nullptr; }
    auto s = exec->tool_history().to_json(count);
    if (s.empty() || s == "[]") { return nullptr; }
    auto* out = static_cast<char*>(std::malloc(s.size() + 1));
    if (out != nullptr) {
        std::memcpy(out, s.data(), s.size());
        out[s.size()] = '\0';
    }
    return out;
}
 
static void wire_tool_executor(entropic_handle_t h) {
    h->tool_executor = std::make_unique<entropic::ToolExecutor>(
        *h->server_manager,
        h->engine->loop_config(),
        h->engine->callbacks(),
        h->engine->build_directive_hooks());
    entropic::ToolExecutionInterface tei;
    tei.process_tool_calls = [](entropic::LoopContext& ctx,
        const std::vector<entropic::ToolCall>& calls,
        void* ud) -> std::vector<entropic::Message> {
        return static_cast<entropic::ToolExecutor*>(ud)
            ->process_tool_calls(ctx, calls);
    };
    tei.user_data = h->tool_executor.get();
    tei.history_json = tool_history_json_thunk;  // P1-11
    tei.free_fn = [](char* p) { std::free(p); };
    // gh#166 (v2.13.0): a bound session's tool calls run against its
    // workspace's own server instances, not the handle's default set.
    h->tool_executor->set_server_resolver(
        +[](const std::string& key, void* ud)
            -> entropic::ServerManager* {
            return entropic::workspace_servers(
                static_cast<entropic_handle_t>(ud), key);
        }, h);
    h->engine->set_tool_executor(tei);
}
 
static char* sp_get_validation(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    if (h == nullptr || h->validator == nullptr) { return nullptr; }
    auto r = h->validator->last_result();
    nlohmann::json v;
    v["ran"] = true;
    switch (r.verdict) {
    case entropic::ValidationVerdict::passed:
        v["verdict"] = "passed"; break;
    case entropic::ValidationVerdict::revised:
        v["verdict"] = "revised"; break;
    case entropic::ValidationVerdict::rejected_reverted_length:
        v["verdict"] = "rejected_reverted_length"; break;
    case entropic::ValidationVerdict::rejected_max_revisions:
        v["verdict"] = "rejected_max_revisions"; break;
    case entropic::ValidationVerdict::skipped:
        v["verdict"] = "skipped"; break;
    case entropic::ValidationVerdict::paused_pending_consumer:
        v["verdict"] = "paused_pending_consumer"; break;
    case entropic::ValidationVerdict::passed_consumer_override:
        v["verdict"] = "passed_consumer_override"; break;
    }
    v["revisions_applied"] = r.revision_count;
    // gh#30 (v2.1.5): structured fields the consumer needs to render
    // a "retry / override / re-prompt" UI without parsing free-form
    // reason strings.
    v["attempt_n"] = r.attempt_n;
    nlohmann::json violations = nlohmann::json::array();
    for (const auto& vi : r.final_critique.violations) {
        violations.push_back({
            {"rule", vi.rule},
            {"rule_id", vi.rule},        // alias for gh#30 schema
            {"rule_text", vi.rule},      // alias for gh#30 schema
            {"excerpt", vi.excerpt},
            {"quote", vi.excerpt},       // alias matching gh#30 "evidence.quote"
            {"explanation", vi.explanation},
            {"severity", "error"},       // gh#30: hard rejection only today
        });
    }
    v["violations"] = violations;
    return strdup(v.dump().c_str());
}
 
static void wire_hooks_and_validator(
    entropic_handle_t h,
    entropic::InferenceInterface& iface,
    const std::string& constitution_text) {
    entropic::HookInterface hook_iface;
    hook_iface.registry = &h->hook_registry;
    hook_iface.fire_pre = [](void* reg, entropic_hook_point_t pt,
        const char* json, char** out) -> int {
        return static_cast<entropic::HookRegistry*>(reg)
            ->fire_pre(pt, json, out);
    };
    hook_iface.fire_post = [](void* reg, entropic_hook_point_t pt,
        const char* json, char** out) {
        static_cast<entropic::HookRegistry*>(reg)
            ->fire_post(pt, json, out);
    };
    hook_iface.fire_info = [](void* reg, entropic_hook_point_t pt,
        const char* json) {
        static_cast<entropic::HookRegistry*>(reg)->fire_info(pt, json);
    };
    h->engine->set_hooks(hook_iface);
    // E9 (2.0.6-rc19): forward the same hook dispatch to the tool
    // executor so PRE_TOOL_CALL / POST_TOOL_CALL actually fire.
    // Prior wiring only touched the engine; tool_executor_ held a
    // null HookInterface and silently skipped all tool hooks.
    if (h->tool_executor) {
        h->tool_executor->set_hooks(hook_iface);
    }
 
    if (h->config.constitutional_validation.enabled
        && !constitution_text.empty()) {
        h->validator = std::make_unique<entropic::ConstitutionalValidator>(
            h->config.constitutional_validation, constitution_text);
        h->validator->attach(&hook_iface, &iface);
        // gh#108 (v2.10.3): resolve reasoning delimiters PER TIER. One
        // validator serves every tier, but thinking format is a per-family
        // property — before this, the validator hardcoded `<think>` and so
        // handed the critique model raw `<|channel>` reasoning on a Gemma-4
        // tier, exactly the failure it exists to prevent. The facade is the
        // lowest layer that can see both, so it owns the lambda; core takes
        // plain strings and keeps no dependency on inference.
        h->validator->set_marker_resolver(
            [h](const std::string& tier)
                -> std::pair<std::string, std::string> {
                auto* adapter = (h->orchestrator != nullptr)
                    ? h->orchestrator->get_adapter(tier) : nullptr;
                if (adapter == nullptr) { return {"<think>", "</think>"}; }
                auto m = adapter->thinking_markers();
                return {m.open, m.close};
            });
        // E3 (2.0.6-rc17): expose validator verdict via ON_COMPLETE
        // hook context.
        h->engine->set_validation_provider(sp_get_validation, h);
        s_log->info("Constitutional validator attached (max_revisions={})",
                     h->config.constitutional_validation.max_revisions);
    }
}
 
// ── State provider callbacks ─────────────────────────────
 
static char* sp_get_config(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    nlohmann::json j;
    j["default_tier"] = h->config.models.default_tier;
    j["log_level"] = h->config.log_level;
    j["log_dir"] = h->config.log_dir.string();
    j["ggml_logging"] = h->config.ggml_logging;
    return strdup(j.dump().c_str());
}
 
static std::string build_assembled_prompt_for_tier(
    entropic_engine* h, const std::string& tier_name) {
    auto data_dir = entropic::config::resolve_data_dir(h->config);
    std::string constitution, app_ctx;
    // gh#156: was two discarded error strings; the shared loader logs them.
    entropic::prompts::load_shared_prompt_sources(
        h->config, data_dir, constitution, app_ctx);
    std::string identity_body;
    auto it = h->config.models.tiers.find(tier_name);
    if (it != h->config.models.tiers.end()) {
        identity_body = entropic::prompts::resolve_tier_identity(
            it->second, tier_name, data_dir);
    }
    std::string out;
    if (!constitution.empty()) { out += constitution + "\n\n"; }
    if (!app_ctx.empty()) { out += app_ctx + "\n\n"; }
    if (!identity_body.empty()) { out += identity_body; }
 
    // gh#87 (v2.7.0): tool defs are no longer string-injected into the
    // system prompt — they flow via params.tools and common_chat renders
    // them in the model's native format. So the assembled system-prompt
    // preview no longer includes a tool section.
    return out;
}
 
static char* sp_get_identities(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    nlohmann::json arr = nlohmann::json::array();
    for (const auto& [name, _] : h->config.models.tiers) {
        nlohmann::json entry;
        entry["name"] = name;
        entry["assembled_prompt"] =
            build_assembled_prompt_for_tier(h, name);
        arr.push_back(std::move(entry));
    }
    return strdup(arr.dump().c_str());
}
 
static char* sp_get_tools(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    if (!h->server_manager) { return strdup("[]"); }
    return strdup(h->server_manager->list_tools().c_str());
}
 
static char* sp_get_history(int max_entries, void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    if (!h || !h->engine) { return strdup("[]"); }
    const auto& msgs = h->engine->get_messages();
    nlohmann::json arr = nlohmann::json::array();
    int start = 0;
    if (max_entries > 0
        && static_cast<int>(msgs.size()) > max_entries) {
        start = static_cast<int>(msgs.size()) - max_entries;
    }
    for (int i = start; i < static_cast<int>(msgs.size()); ++i) {
        const auto& m = msgs[static_cast<size_t>(i)];
        std::string preview = m.content.size() > 200
            ? entropic::facade::utf8_safe_substr(m.content, 200) + "..."
            : m.content;
        arr.push_back({
            {"role",             m.role},
            {"content_preview",  preview},
            {"token_count_est",  m.content.size() / 4u}
        });
    }
    return strdup(arr.dump().c_str());
}
 
static char* sp_get_residency(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    if (!h || !h->orchestrator) {
        return strdup("{\"vram_total_bytes\":0,\"vram_budget_bytes\":0,"
                      "\"vram_headroom_bytes\":0,\"backend\":\"unknown\","
                      "\"residency\":[]}");
    }
    return strdup(h->orchestrator->residency_snapshot_json().c_str());
}
 
static char* sp_get_state(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    nlohmann::json j;
    j["engine_state"] = h->configured.load() ? "configured" : "init";
    j["default_tier"] = h->config.models.default_tier;
 
    nlohmann::json tiers = nlohmann::json::array();
    for (const auto& [name, _] : h->config.models.tiers) {
        tiers.push_back(name);
    }
    j["active_tiers"] = tiers;
 
    if (h->server_manager) {
        j["working_dir"] = h->server_manager->project_dir().string();
        j["registered_servers"] = h->server_manager->server_names();
    }
    j["data_dir"] = entropic::config::resolve_data_dir(
        h->config).string();
    j["log_dir"] = h->config.log_dir.string();
    return strdup(j.dump().c_str());
}
 
static nlohmann::json generations_json(entropic_engine* h) {
    nlohmann::json arr = nlohmann::json::array();
    if (h == nullptr || !h->orchestrator) { return arr; }
    for (const auto& rec : h->orchestrator->generation_records()) {
        arr.push_back({
            {"finish_reason",    rec.finish_reason},
            {"token_count",      rec.token_count},
            {"prefill_tokens",   rec.prefill_tokens},
            {"throughput_tok_s", rec.throughput_tok_s},
            {"n_drafted",        rec.n_drafted},
            {"n_accepted",       rec.n_accepted},
            {"grammar", {
                {"source",          rec.grammar.source},
                {"key",             rec.grammar.key},
                {"resolved",        rec.grammar.resolved},
                {"conflict_winner", rec.grammar.conflict_winner},
            }},
        });
    }
    return arr;
}
 
static char* sp_get_metrics(void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    if (!h || !h->engine) { return strdup("{}"); }
    auto m = h->engine->last_loop_metrics();
    nlohmann::json j;
    j["generations"] = generations_json(h);
    j["iterations"]  = m.iterations;
    j["tool_calls"]  = m.tool_calls;
    j["tokens_used"] = m.tokens_used;
    j["errors"]      = m.errors;
    j["duration_ms"] = m.duration_ms();
    // Per-tier breakdown (P2-15 follow-up, 2.0.6-rc16.2)
    nlohmann::json per_tier = nlohmann::json::object();
    for (auto& [tier, tm] : h->engine->per_tier_metrics()) {
        per_tier[tier] = {
            {"iterations",  tm.iterations},
            {"tool_calls",  tm.tool_calls},
            {"tokens_used", tm.tokens_used},
            {"errors",      tm.errors},
            {"duration_ms", tm.duration_ms()},
        };
    }
    j["per_tier"] = per_tier;
    return strdup(j.dump().c_str());
}
 
static char* sp_get_docs(const char* section, void* ud) {
    (void)section;
    (void)ud;
    return strdup("");
}
 
static char* sp_search_delegations(
        const char* query, int max_results, void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    std::string out;
    if (h == nullptr || !h->storage || query == nullptr
        || !h->storage->search_delegations(query, max_results, out)) {
        return nullptr;
    }
    auto rows = nlohmann::json::parse(out, nullptr, false);
    nlohmann::json records = nlohmann::json::array();
    for (const auto& r : rows.is_array() ? rows : nlohmann::json::array()) {
        nlohmann::json rec;
        rec["delegation_id"] = r.value("id", "");
        rec["target_tier"] = r.value("target_tier", "");
        rec["summary"] = r.value("result_summary", "");
        rec["completed_at"] = r.value("completed_at", "");
        records.push_back(std::move(rec));
    }
    return strdup(records.dump().c_str());
}
 
static char* sp_load_delegation_conversation(
        const char* delegation_id, void* ud) {
    auto* h = static_cast<entropic_engine*>(ud);
    if (h == nullptr || !h->storage || delegation_id == nullptr) {
        return nullptr;
    }
    std::string out;
    if (!si_load_delegation_with_messages(
            delegation_id, out, h->storage.get())) {
        return nullptr;
    }
    return strdup(out.c_str());
}
 
static void wire_state_provider(entropic_handle_t h) {
    if (!h->server_manager) { return; }
    auto* es = dynamic_cast<entropic::EntropicServer*>(
        h->server_manager->get_server("entropic"));
    if (es == nullptr) { return; }
 
    entropic_state_provider_t sp{};
    sp.get_config = sp_get_config;
    sp.get_identities = sp_get_identities;
    sp.get_tools = sp_get_tools;
    sp.get_history = sp_get_history;
    sp.get_state = sp_get_state;
    sp.get_metrics = sp_get_metrics;
    sp.get_docs = sp_get_docs;
    // gh#32 (v2.1.6): storage-backed delegation recall + resume.
    sp.search_delegations = sp_search_delegations;
    sp.load_delegation_conversation = sp_load_delegation_conversation;
    // gh#57 (v2.2.4): VRAM residency-set snapshot.
    sp.get_residency = sp_get_residency;
    sp.user_data = h;
    es->set_state_provider(sp);
    s_log->info("State provider wired to entropic server");
}
 
static void wire_tier_validation_rules(entropic_handle_t h) {
    if (!h->validator) { return; }
    for (const auto& [name, rules] : h->tier_validation_rules) {
        h->validator->set_tier_rules(name, rules);
    }
}
 
// ── gh#160: delegation isolation wiring ────────────────────
 
static std::filesystem::path facade_session_root(
    const std::string& session_key, void* ud) {
    auto* h = static_cast<entropic_handle_t>(ud);
    auto* servers = entropic::workspace_servers(h, session_key);
    if (servers == nullptr) { return {}; }
    return servers->project_dir();
}
 
static std::vector<std::string> facade_unsafe_external_tools(
    const std::string& session_key,
    const std::vector<std::string>& allowed, void* ud) {
    auto* h = static_cast<entropic_handle_t>(ud);
    auto* servers = entropic::workspace_servers(h, session_key);
    if (servers == nullptr) { return {}; }
    // gh#166: a workspace's external servers connect when the workspace is
    // created, so their annotations are already cached by the time a
    // delegation is admitted — no lazy spawn is needed at the gate.
    return servers->external_tools_without_readonly_hint(allowed);
}
 
static void wire_session_roots(entropic_handle_t h) {
    entropic::SessionRootInterface iface;
    iface.resolve_root = facade_session_root;
    iface.unsafe_external_tools = facade_unsafe_external_tools;
    iface.user_data = h;
    h->engine->set_session_root_interface(iface);
    h->engine->set_dir_swap(entropic::swap_session_tool_dir, h);
}
 
static entropic::LoopConfig build_loop_config(entropic_handle_t h) {
    entropic::LoopConfig lc;
    // gh#110 (v2.9.6): was hardcoded true, making the agent loop always
    // stream and therefore permanently out of MTP's envelope (MTP
    // rejects a bound on_token callback — see mtp_envelope.h).
    lc.stream_output = h->config.generation.stream_output;
    lc.speculative_enabled = h->config.inference.speculative.enabled;
    // gh#160 (v2.13.0): opt-in delegation sandboxing. OFF means no
    // snapshot is taken at all — the wasted copy the issue reported
    // disappears with the feature it was never serving.
    lc.delegation_isolation =
        h->config.delegation.isolation
        == entropic::DelegationIsolation::sandbox;
    lc.auto_approve_tools = h->config.permissions.auto_approve;
    auto it = h->config.models.tiers.find(h->config.models.default_tier);
    if (it != h->config.models.tiers.end()) {
        lc.context_length = it->second.context_length;
    }
    // gh#80 (v2.5.0): map the generation.budget_mode string to the
    // BudgetMode enum. Unknown values resolve to off with a warning.
    const std::string& bm = h->config.generation.budget_mode;
    if (bm == "tokens") {
        lc.budget_mode = entropic::BudgetMode::tokens;
    } else if (bm == "wall_clock") {
        lc.budget_mode = entropic::BudgetMode::wall_clock;
    } else {
        if (bm != "off") {
            s_log->warn("Unknown generation.budget_mode '{}' — "
                        "treating as 'off'", bm);
        }
        lc.budget_mode = entropic::BudgetMode::off;
    }
    lc.budget_limit = h->config.generation.budget_limit;
    // A non-positive limit can't gate anything — disable to avoid a
    // pathological "exhausted at zero" loop.
    if (lc.budget_limit <= 0) {
        lc.budget_mode = entropic::BudgetMode::off;
    }
    return lc;
}
 
static entropic_error_t start_http_listener(entropic_handle_t h) {
    const int port = h->config.mcp.external.http_port;
    std::string err;
    if (port != 0 && (port < 0 || port > 65535)) {
        err = "mcp.external.http_port out of range: " + std::to_string(port);
    } else if (port != 0 && !h->external_bridge) {
        err = "the unix bridge did not start";
    } else if (port != 0) {
        h->http_listener = std::make_unique<entropic::http::HttpListener>(
            h->external_bridge.get(), port);
        if (!h->http_listener->start(err)) { h->http_listener.reset(); }
    }
    if (!err.empty()) {
        h->last_error = "HTTP listener: " + err;
        s_log->error("{}", h->last_error);
    }
    return err.empty() ? ENTROPIC_OK : ENTROPIC_ERROR_IO;
}
 
static void start_external_bridge(entropic_handle_t h) {
    if (!h->config.mcp.external.enabled) { return; }
    // Same derivation the self-connection guard uses (gh#200).
    h->external_bridge = std::make_unique<entropic::ExternalBridge>(
        h, h->config.mcp.external, entropic::bridge_project_dir(h));
    if (!h->external_bridge->start()) {
        s_log->warn("External MCP bridge failed to start");
        h->external_bridge.reset();
    }
}
 
static entropic_error_t reject_if_configured(entropic_handle_t h) {
    if (!h->configured.load()) { return ENTROPIC_OK; }
    h->last_error = "handle already configured";
    s_log->error("{}", h->last_error);
    return ENTROPIC_ERROR_INVALID_STATE;
}
 
static entropic_error_t init_orchestrator(
    entropic_handle_t h, const std::filesystem::path& data_dir) {
    h->orchestrator = std::make_unique<entropic::ModelOrchestrator>();
    if (!h->orchestrator->initialize(h->config)) {
        h->last_error = "orchestrator initialization failed";
        s_log->error("{}", h->last_error);
        return ENTROPIC_ERROR_LOAD_FAILED;
    }
    // Fallback grammar loading: only if initialize() didn't find
    // grammars via config_dir. Avoids overwriting patched grammars.
    if (h->orchestrator->grammar_registry().size() == 0) {
        h->orchestrator->load_grammars_from(data_dir / "grammars");
    }
    return ENTROPIC_OK;
}
 
static void init_engine_and_interfaces(
    entropic_handle_t h, const std::filesystem::path& data_dir) {
    h->mcp_auth = std::make_unique<entropic::MCPAuthorizationManager>();
    h->identity_manager = std::make_unique<entropic::IdentityManager>(
        entropic::IdentityManagerConfig{});
    // P1-7: route identity changes to prompt-cache invalidation.
    h->identity_manager->set_cache_invalidator(
        [](void* ud) {
            auto* orch = static_cast<entropic::ModelOrchestrator*>(ud);
            if (orch) { orch->clear_all_prompt_caches(); }
        }, h->orchestrator.get());
    init_mcp_servers(h, data_dir);
 
    // gh#58 follow-up (v2.2.6): per-handle InterfaceContext. Pre-v2.2.6
    // build_orchestrator_interface stored the context in a process-
    // global static, so a second configure freed the first handle's
    // context and h1.run() segfaulted on a use-after-free.
    h->inference_iface = entropic::build_orchestrator_interface(
        h->orchestrator.get(), h->config.models.default_tier,
        &h->inference_iface_ctx);
    h->inference_iface.get_tool_prompt = facade_get_tool_prompt;
    h->inference_iface.tool_prompt_data = h;
    auto lc = build_loop_config(h);
    h->engine = std::make_unique<entropic::AgentEngine>(
        h->inference_iface, lc, h->config.compaction);
    // gh#76 (v2.3.27): wire the compactor registry now that the engine
    // owns the CompactionManager that backs the default-compactor
    // fallback. Pre-v2.3.27 the field was declared but never
    // constructed, so every `entropic_register_compactor` /
    // `entropic_compact` call returned INVALID_STATE.
    h->compactor_registry =
        std::make_unique<entropic::CompactorRegistry>(
            h->engine->compaction_manager());
    rewire_observers(h);  // gh#40 + fallout (v2.1.10)
    wire_external_interrupt(h);  // P1-10
    // gh#158 (v2.13.0): opt-in per-session-key run concurrency, default off.
    h->engine->set_concurrent_sessions(h->config.concurrent_sessions);
    wire_session_roots(h);  // gh#160
    wire_tool_executor(h);
}
 
static void wire_prompts_and_persistence(
    entropic_handle_t h, const std::filesystem::path& data_dir) {
    auto shared_prefix = build_shared_prompt_prefix(h, data_dir);
    cache_tier_allowed_tools(h, data_dir);       // gh#121: must fill h->tier_allowed_tools
    populate_tier_info(h, data_dir, shared_prefix);  // before populate reads it
    h->engine->set_handoff_rules(h->config.routing.handoff_rules);
 
    wire_hooks_and_validator(h, h->inference_iface, shared_prefix);
    wire_tier_validation_rules(h);
 
    init_persistence(h);
    wire_state_provider(h);
 
    h->engine->set_system_prompt(
        entropic::prompts::assemble(h->config, data_dir));
    if (h->session_logger) {
        h->engine->set_session_logger(h->session_logger.get());
    }
}
 
static entropic_error_t validate_prompt_sources(
    entropic_handle_t h, const std::filesystem::path& data_dir) {
    auto err = entropic::prompts::validate_configured_prompts(
        h->config, data_dir);
    entropic_error_t rc = ENTROPIC_OK;
    if (!err.empty()) {
        h->last_error = err;
        s_log->error("configure: {}", err);
        rc = ENTROPIC_ERROR_INVALID_CONFIG;
    }
    return rc;
}
 
static void warn_tier_grammars_step(
    entropic_handle_t h, const std::filesystem::path& data_dir) {
    auto warning = entropic::config::warn_unresolved_tier_grammars(
        h->config,
        entropic::config::grammar_search_paths(h->config, data_dir));
    if (!warning.empty()) {
        s_log->warn("configure: {}", warning);
    }
}
 
static entropic_error_t configure_common(entropic_handle_t h) {
    auto rc = reject_if_configured(h);
    if (rc != ENTROPIC_OK) { return rc; }
    // gh#59 follow-up (v2.3.7): honor console_logging before any init
    // logging fires. When false, strip the stderr console sink so the
    // file sink (already installed by setup_session) is the only route
    // — TUI consumers paint to fd 2 and can't tolerate engine output
    // there. Default (true) is a no-op; operators keep stderr logs.
    entropic::log::set_console_enabled(h->config.console_logging);
    auto data_dir = entropic::config::resolve_data_dir(h->config);
    // gh#156 (v2.13.0): a configured constitution / app_context path that
    // cannot be loaded is a config error, and it is raised HERE — before
    // init_orchestrator loads the model.
    rc = validate_prompt_sources(h, data_dir);
    if (rc == ENTROPIC_OK) {
        // gh#94 (v2.7.3): thread per-tier frontmatter samplers into the
        // config BEFORE the orchestrator snapshots it by value. The
        // engine-bound frontmatter wiring stays in
        // wire_prompts_and_persistence (post-engine).
        thread_frontmatter_samplers(h, data_dir);
        // gh#154 (v2.13.0): name a tier grammar stem that does not resolve
        // YET. Not a refusal — entropic_grammar_register* needs the
        // orchestrator this call is about to build, so a consumer's only
        // legal order is configure-then-register. The run that selects the
        // tier is what fails, loudly and typed, if nobody ever did.
        warn_tier_grammars_step(h, data_dir);
    }
    if (rc == ENTROPIC_OK) {
        rc = init_orchestrator(h, data_dir);
    }
    if (rc != ENTROPIC_OK) { return rc; }
 
    init_engine_and_interfaces(h, data_dir);
    wire_prompts_and_persistence(h, data_dir);
 
    h->configured.store(true);
    start_external_bridge(h);
    // gh#204: an explicitly configured HTTP listener that cannot start fails
    // configure, so a headless host exits instead of running unreachable.
    const auto http_rc = start_http_listener(h);
    s_log->info("configure complete");
    return http_rc;
}
 
static entropic_error_t do_configure_json(
    entropic_handle_t handle, const char* config_json) {
    handle->bundled_models.auto_discover_and_load();
    auto err = entropic::config::load_config_from_string(
        config_json, handle->bundled_models, handle->config);
    if (!err.empty()) {
        handle->last_error = err;
        s_log->error("configure: {}", err);
        return ENTROPIC_ERROR_INVALID_CONFIG;
    }
    // gh#109 follow-up: parity with configure_dir/configure_from_file.
    // Without this, a JSON-string config that sets "log_dir" got no
    // session.log at all — config.log_dir was honored for the sqlite/
    // conversation store (init_persistence) but never wired to the
    // per-handle log dispatcher, so no file sink existed for any
    // HandleLogScope-tagged log line to route to.
    if (!handle->config.log_dir.empty()) {
        entropic::log::setup_session(handle->config.log_dir);
        entropic::log::register_handle_log(
            handle->log_id, handle->config.log_dir);
    }
    return configure_common(handle);
}
 
entropic_error_t entropic_configure(
    entropic_handle_t handle,
    const char* config_json) {
    if (!handle || !config_json) {
        return !handle ? ENTROPIC_ERROR_INVALID_HANDLE
                       : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    return c_api_try(handle,
        [&]() { return do_configure_json(handle, config_json); });
}
 
static entropic_error_t do_configure_from_file(
    entropic_handle_t handle, const char* config_path) {
    handle->bundled_models.auto_discover_and_load();
    auto err = entropic::config::load_config_from_file(
        config_path, handle->bundled_models, handle->config);
    if (!err.empty()) {
        handle->last_error = err;
        s_log->error("configure_from_file: {}", err);
        return ENTROPIC_ERROR_INVALID_CONFIG;
    }
    // Parity with configure_dir: if the parsed config specifies a
    // log_dir, start session logging there. Without this, consumers
    // using the file-based API get no session.log on disk even when
    // their YAML declares log_dir.
    if (!handle->config.log_dir.empty()) {
        entropic::log::setup_session(handle->config.log_dir);
        // gh#59 (v2.3.1): per-handle dispatcher file sink so log lines
        // emitted within this handle's HandleLogScope route to this
        // handle's session.log only.
        entropic::log::register_handle_log(
            handle->log_id, handle->config.log_dir);
    }
    return configure_common(handle);
}
 
entropic_error_t entropic_configure_from_file(
    entropic_handle_t handle,
    const char* config_path) {
    if (!handle || !config_path) {
        return !handle ? ENTROPIC_ERROR_INVALID_HANDLE
                       : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    return c_api_try(handle,
        [&]() { return do_configure_from_file(handle, config_path); });
}
 
static entropic_error_t do_configure_dir(
    entropic_handle_t handle, const char* project_dir) {
    // Session logging FIRST — capture everything from preload through init.
    if (project_dir && project_dir[0] != '\0') {
        entropic::log::setup_session(project_dir);
        // gh#59 (v2.3.1): per-handle dispatcher registration. Routes
        // session.log writes for this handle's HandleLogScope-tagged
        // threads to this handle's file only — no cross-handle bleed.
        entropic::log::register_handle_log(handle->log_id, project_dir);
    }
    handle->bundled_models.auto_discover_and_load();
    std::filesystem::path proj_dir = (project_dir && project_dir[0] != '\0')
        ? project_dir : "";
    auto err = entropic::config::load_layered(
        proj_dir, "default_config.yaml",
        handle->bundled_models, handle->config);
    if (!err.empty()) {
        handle->last_error = err;
        s_log->error("configure_dir: {}", err);
        return ENTROPIC_ERROR_INVALID_CONFIG;
    }
    auto rc = configure_common(handle);
    // gh#31 (v2.1.6): propagate the configured project_dir into the
    // engine so `AgentEngine::get_repo_dir()` uses it as the sandbox
    // snapshot source.
    if (rc == ENTROPIC_OK && handle->engine && !proj_dir.empty()) {
        handle->engine->set_project_dir(std::filesystem::absolute(proj_dir));
    }
    return rc;
}
 
entropic_error_t entropic_configure_dir(
    entropic_handle_t handle,
    const char* project_dir) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    return c_api_try(handle,
        [&]() { return do_configure_dir(handle, project_dir); });
}
 
void entropic_destroy(entropic_handle_t handle) {
    if (handle == nullptr) {
        return;
    }
    s_log->info("entropic_destroy()");
 
    // Stop external bridge FIRST — it holds a raw pointer to handle
    // gh#204: the HTTP front end dispatches into the bridge — stop it first.
    handle->http_listener.reset();
    if (handle->external_bridge) {
        handle->external_bridge->stop();
        handle->external_bridge.reset();
    }
 
    entropic_inference_log_silence();
 
    // gh#58 follow-up (v2.2.6): release per-handle InterfaceContext
    // before the orchestrator unloads, since the context holds a raw
    // orchestrator pointer used by the iface callbacks.
    entropic::destroy_orchestrator_interface(handle->inference_iface_ctx);
    handle->inference_iface_ctx = nullptr;
 
    // gh#166 (v2.13.0): named workspaces own server instances with live
    // child processes. Shut them down explicitly, before the engine that
    // may still hold a resolver pointing at them goes away — teardown
    // order is the recurring gh#58 failure shape, not left to chance.
    {
        std::lock_guard<std::mutex> guard(handle->workspace_mutex);
        for (auto& [name, ws] : handle->workspaces) {
            if (ws && ws->servers) { ws->servers->shutdown(); }
        }
        handle->workspaces.clear();
        handle->session_workspace.clear();
    }
 
    // gh#59 (v2.3.1): release the per-handle session.log file sink so
    // a subsequent handle that happens to reuse the same log_id can
    // open the file fresh. Safe on never-registered ids.
    entropic::log::unregister_handle_log(handle->log_id);
 
    // Phase 1+ subsystem teardown will go here in reverse order.
    // Phase 0: struct itself owns hook_registry by value.
    delete handle;
}
 
const char* entropic_version(void) {
    return CONFIG_ENTROPIC_VERSION_STRING;
}
 
int entropic_api_version(void) {
    return 2;
}
 
int64_t entropic_seconds_since_last_activity(entropic_handle_t handle) {
    if (!handle || !handle->engine) { return 0; }
    return handle->engine->seconds_since_last_activity();
}
 
void* entropic_alloc(size_t size) {
    return malloc(size);
}
 
void entropic_free(void* ptr) {
    free(ptr);
}
 
entropic_error_t entropic_run(
    entropic_handle_t handle,
    const char* input,
    char** result_json) {
    // gh#109: NO api_mutex — a long turn must not block entropic_interrupt()
    // called from another thread. gh#144 (v2.12.0): the claim is a single
    // compare-exchange, so that property holds by construction. The guard is
    // declared BEFORE validation but claim() is evaluated LAST in the chain
    // below, so a call rejected for a bad argument never momentarily claims
    // the engine and bounces a legitimate concurrent caller.
    entropic::HandleTurnGuard turn(handle);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !input || !result_json || !handle->engine
        || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!input || !result_json) ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : !handle->engine ? ENTROPIC_ERROR_INVALID_STATE
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    try {
        auto result = handle->engine->run_turn(input);
        *result_json = alloc_cstr(
            facade_json::serialize_messages(result));
        // Synthetic completion sentinel — lets observers detect the
        // end of a non-streaming run. Contract: (token="", len=0).
        // (P0-1, 2.0.6-rc16)
        if (handle->stream_observer != nullptr) {
            handle->stream_observer(
                "", 0, handle->stream_observer_data);
        }
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run: {}", handle->last_error);
        // P3-19 follow-up (2.0.6-rc16.2): surface partial context on
        // crash so callers can recover tool_results and any partial
        // assistant content accumulated before the failure.
        try {
            *result_json = alloc_cstr(
                facade_json::serialize_messages(
                    handle->engine->get_messages()));
        } catch (...) {
            *result_json = nullptr;
        }
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
static entropic_error_t run_as_inner(
    entropic_handle_t handle, const char* tier, const char* input,
    char** result_json) {
    try {
        auto result = handle->engine->run_turn_as(tier, input);
        *result_json = alloc_cstr(facade_json::serialize_messages(result));
        // Synthetic completion sentinel (token="", len=0), matching run().
        if (handle->stream_observer != nullptr) {
            handle->stream_observer("", 0, handle->stream_observer_data);
        }
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_as: {}", handle->last_error);
        // Define *result_json on the error path, matching entropic_run()'s
        // documented identical contract: surface partial context, else nullptr.
        try {
            *result_json = alloc_cstr(
                facade_json::serialize_messages(handle->engine->get_messages()));
        } catch (...) {
            *result_json = nullptr;
        }
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
entropic_error_t entropic_run_as(
    entropic_handle_t handle,
    const char* tier_or_identity,
    const char* input,
    char** result_json) {
    // gh#109: NO api_mutex — a long turn must not block entropic_interrupt()
    // called from another thread. gh#144 (v2.12.0): the claim is a single
    // compare-exchange, so that property holds by construction. The guard is
    // declared BEFORE validation but claim() is evaluated LAST in the chain
    // below, so a call rejected for a bad argument never momentarily claims
    // the engine and bounces a legitimate concurrent caller.
    entropic::HandleTurnGuard turn(handle);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !tier_or_identity || !input || !result_json
        || !handle->engine || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!tier_or_identity || !input || !result_json)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : !handle->engine ? ENTROPIC_ERROR_INVALID_STATE
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    if (!handle->engine->has_tier(tier_or_identity)) {
        handle->last_error =
            std::string("unknown tier: ") + tier_or_identity;
        s_log->error("run_as: {}", handle->last_error);
        return ENTROPIC_ERROR_IDENTITY_NOT_FOUND;
    }
    return run_as_inner(handle, tier_or_identity, input, result_json);
}
 
static std::string serialize_batch_results(
    const std::vector<entropic::GenerationResult>& results) {
    nlohmann::json arr = nlohmann::json::array();
    for (const auto& r : results) {
        nlohmann::json obj;
        obj["content"] = entropic::mcp::sanitize_utf8(r.content);
        obj["finish_reason"] = r.finish_reason;
        obj["tool_calls"] = nlohmann::json::parse(
            entropic::serialize_tool_calls(r.tool_calls), nullptr, false);
        arr.push_back(std::move(obj));
    }
    return arr.dump();
}
 
static std::vector<std::vector<entropic::Message>> build_batch_messages(
    entropic_handle_t handle, const char** tiers, const char** prompts,
    size_t n, std::vector<std::string>& tiers_out) {
    std::vector<std::vector<entropic::Message>> msgs(n);
    tiers_out.resize(n);
    for (size_t i = 0; i < n; ++i) {
        tiers_out[i] = (tiers && tiers[i]) ? tiers[i] : "";
        const std::string& sys =
            handle->engine->tier_system_prompt(tiers_out[i]);
        std::vector<entropic::Message> m;
        if (!sys.empty()) {
            entropic::Message s;
            s.role = "system";
            s.content = sys;
            m.push_back(std::move(s));
        }
        entropic::Message u;
        u.role = "user";
        u.content = prompts[i] ? prompts[i] : "";
        m.push_back(std::move(u));
        msgs[i] = std::move(m);
    }
    return msgs;
}
 
entropic_error_t entropic_run_batch(
    entropic_handle_t handle,
    const char** tiers,
    const char** prompts,
    size_t n,
    char** result_json) {
    // gh#109: NO api_mutex — a long turn must not block entropic_interrupt()
    // called from another thread. gh#144 (v2.12.0): the claim is a single
    // compare-exchange, so that property holds by construction. The guard is
    // declared BEFORE validation but claim() is evaluated LAST in the chain
    // below, so a call rejected for a bad argument never momentarily claims
    // the engine and bounces a legitimate concurrent caller.
    entropic::HandleTurnGuard turn(handle);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !prompts || !result_json || !handle->engine
        || n == 0 || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!prompts || !result_json || n == 0)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : !handle->engine ? ENTROPIC_ERROR_INVALID_STATE
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    try {
        std::vector<std::string> tiers_vec;
        auto msgs = build_batch_messages(handle, tiers, prompts, n, tiers_vec);
        std::vector<entropic::GenerationParams> params(n);
        // gh#158 (v2.13.0): this was a LOCAL `std::atomic<bool> cancel{false}`
        // that nothing in the tree could ever set, so a batch was
        // uninterruptible — `entropic_interrupt()` returned OK and the batch
        // ran to completion. The run's own cancel token is the flag the
        // handle-wide interrupt and `entropic_interrupt_session` both set,
        // and `run_batch_gen_loop` already polls its argument per step.
        std::atomic<bool>& cancel = handle->engine->run_cancel_flag();
        auto results = handle->orchestrator->generate_batch(
            msgs, params, tiers_vec, cancel);
        *result_json = alloc_cstr(serialize_batch_results(results));
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_batch: {}", handle->last_error);
        // Define *result_json on the error path (C-ABI: output params must be
        // defined). No partial batch recovery — an empty JSON array.
        *result_json = alloc_cstr("[]");
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
/* StreamBridge + think filter moved to inference/stream_think_filter.cpp — Step 4 */
 
/* StreamCtx + stream_chunk_cb → engine->run_streaming() — v2.0.2 */
 
entropic_error_t entropic_run_streaming(
    entropic_handle_t handle,
    const char* input,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag) {
    // gh#109: NO api_mutex — a long turn must not block entropic_interrupt()
    // called from another thread. gh#144 (v2.12.0): the claim is a single
    // compare-exchange, so that property holds by construction. The guard is
    // declared BEFORE validation but claim() is evaluated LAST in the chain
    // below, so a call rejected for a bad argument never momentarily claims
    // the engine and bounces a legitimate concurrent caller.
    entropic::HandleTurnGuard turn(handle);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !input || !on_token || !handle->engine
        || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!input || !on_token || !handle->engine)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
 
 
    // Observer multiplexing is handled inside ResponseGenerator — the
    // facade passes on_token through untouched. (P0-1, 2.0.6-rc16)
    try {
        int code = handle->engine->run_streaming(
            input, on_token, user_data, cancel_flag);
        if (handle->stream_observer != nullptr) {
            handle->stream_observer(
                "", 0, handle->stream_observer_data);
        }
        return code == 1 ? ENTROPIC_ERROR_CANCELLED : ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_streaming: {}", handle->last_error);
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
// ── gh#37 (v2.1.8): multimodal messages entry points ──────────
 
static std::vector<entropic::Message> parse_and_check_vision(
    entropic_handle_t handle,
    const char* messages_json,
    entropic_error_t& out_rc) {
    auto msgs = entropic::parse_messages_json(messages_json);
    if (entropic::any_message_has_images(msgs)
            && handle->orchestrator
            && !handle->orchestrator->has_vision_capable_tier()) {
        out_rc = ENTROPIC_ERROR_NO_VISION_TIER;
        return {};
    }
    out_rc = ENTROPIC_OK;
    return msgs;
}
 
static entropic_error_t run_messages_inner(
    entropic_handle_t handle,
    const char* messages_json,
    char** result_json) {
    entropic_error_t vrc = ENTROPIC_OK;
    auto msgs = parse_and_check_vision(handle, messages_json, vrc);
    if (vrc != ENTROPIC_OK) { return vrc; }
    auto result = handle->engine->run_turn(std::move(msgs));
    *result_json = alloc_cstr(
        facade_json::serialize_messages(result));
    if (handle->stream_observer != nullptr) {
        handle->stream_observer(
            "", 0, handle->stream_observer_data);
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_run_messages(
    entropic_handle_t handle,
    const char* messages_json,
    char** result_json) {
    // gh#109: NO api_mutex — a long turn must not block entropic_interrupt()
    // called from another thread. gh#144 (v2.12.0): the claim is a single
    // compare-exchange, so that property holds by construction. The guard is
    // declared BEFORE validation but claim() is evaluated LAST in the chain
    // below, so a call rejected for a bad argument never momentarily claims
    // the engine and bounces a legitimate concurrent caller.
    entropic::HandleTurnGuard turn(handle);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !messages_json || !result_json
            || !handle->engine || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!messages_json || !result_json || !handle->engine)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    try {
        return run_messages_inner(handle, messages_json, result_json);
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_messages: {}", handle->last_error);
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
static entropic_error_t run_messages_stream_inner(
    entropic_handle_t handle,
    const char* messages_json,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag) {
    entropic_error_t vrc = ENTROPIC_OK;
    auto msgs = parse_and_check_vision(handle, messages_json, vrc);
    if (vrc != ENTROPIC_OK) { return vrc; }
    int code = handle->engine->run_streaming(
        std::move(msgs), on_token, user_data, cancel_flag);
    if (handle->stream_observer != nullptr) {
        handle->stream_observer(
            "", 0, handle->stream_observer_data);
    }
    return code == 1 ? ENTROPIC_ERROR_CANCELLED : ENTROPIC_OK;
}
 
entropic_error_t entropic_run_messages_streaming(
    entropic_handle_t handle,
    const char* messages_json,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag) {
    // gh#109: NO api_mutex — a long turn must not block entropic_interrupt()
    // called from another thread. gh#144 (v2.12.0): the claim is a single
    // compare-exchange, so that property holds by construction. The guard is
    // declared BEFORE validation but claim() is evaluated LAST in the chain
    // below, so a call rejected for a bad argument never momentarily claims
    // the engine and bounces a legitimate concurrent caller.
    entropic::HandleTurnGuard turn(handle);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !messages_json || !on_token
            || !handle->engine || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!messages_json || !on_token || !handle->engine)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    try {
        return run_messages_stream_inner(
            handle, messages_json, on_token, user_data, cancel_flag);
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_messages_streaming: {}", handle->last_error);
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
entropic_error_t entropic_set_stream_observer(
    entropic_handle_t handle,
    void (*observer)(const char* token, size_t len, void* user_data),
    void* user_data) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    handle->stream_observer = observer;
    handle->stream_observer_data = user_data;
    // Propagate to engine so every generation path (streaming, batch,
    // and child-loop delegations) reaches the observer. (P0-1, 2.0.6-rc16)
    if (handle->engine) {
        handle->engine->set_stream_observer(observer, user_data);
    }
    return ENTROPIC_OK;
}
 
// ── gh#30 (v2.1.5): validation retry controls ─────────────
 
entropic_error_t entropic_validation_set_auto_retry(
    entropic_handle_t handle, int enabled) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (handle->validator) {
        handle->validator->set_auto_retry(enabled != 0);
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_validation_resume_retry(
    entropic_handle_t handle) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!handle->validator) { return ENTROPIC_ERROR_INVALID_STATE; }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    return handle->validator->resume_retry();
}
 
entropic_error_t entropic_validation_accept_last(
    entropic_handle_t handle) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!handle->validator) { return ENTROPIC_ERROR_INVALID_STATE; }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    return handle->validator->accept_last();
}
 
entropic_error_t entropic_set_attempt_boundary_cb(
    entropic_handle_t handle,
    ent_validation_attempt_boundary_cb cb,
    void* user_data) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (handle->validator) {
        handle->validator->set_attempt_boundary_cb(cb, user_data);
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_set_delegation_callbacks(
    entropic_handle_t handle,
    ent_delegation_start_cb on_start,
    ent_delegation_complete_cb on_complete,
    void* user_data) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (handle->engine) {
        handle->engine->set_delegation_callbacks(
            on_start, on_complete, user_data);
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_set_state_observer(
    entropic_handle_t handle,
    void (*observer)(int state, void* user_data),
    void* user_data) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    handle->state_observer = observer;
    handle->state_observer_data = user_data;
    if (handle->engine) {
        // gh#40 fallout (v2.1.10): route through the engine's
        // persistent state-observer slot rather than the legacy
        // EngineCallbacks::on_state_change. The legacy path is
        // wiped by run_streaming's set_callbacks() shuffle, so
        // wiring there silently failed for streaming runs (the
        // exact bridge use case this API was designed for).
        handle->engine->set_state_observer(observer, user_data);
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_set_critique_callbacks(
    entropic_handle_t handle,
    void (*start_cb)(void* user_data),
    void (*end_cb)(void* user_data),
    void* user_data) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    handle->critique_start_cb = start_cb;
    handle->critique_end_cb = end_cb;
    handle->critique_cb_data = user_data;
    if (handle->validator) {
        handle->validator->set_critique_callbacks(
            start_cb, end_cb, user_data);
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_interrupt(entropic_handle_t handle) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!handle->engine) { return ENTROPIC_ERROR_INVALID_STATE; }
    handle->engine->interrupt();
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_interrupt_session(
    entropic_handle_t handle,
    const char* session_key) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!handle->engine) { return ENTROPIC_ERROR_INVALID_STATE; }
    const bool found = handle->engine->interrupt_session(
        session_key != nullptr ? session_key : "");
    return found ? ENTROPIC_OK : ENTROPIC_ERROR_NOT_RUNNING;
}
 
// ── Mid-generation user-message queue (gh#40, v2.1.10) ────────
 
entropic_error_t entropic_queue_user_message(
    entropic_handle_t handle, const char* message) {
    entropic_error_t rc = ENTROPIC_OK;
    if (!handle) {
        rc = ENTROPIC_ERROR_INVALID_HANDLE;
    } else if (!message) {
        rc = ENTROPIC_ERROR_INVALID_ARGUMENT;
    } else if (!handle->engine || !handle->engine->is_running()) {
        rc = ENTROPIC_ERROR_INVALID_STATE;
    } else if (!handle->engine->queue_user_message(message)) {
        rc = ENTROPIC_ERROR_QUEUE_FULL;
    }
    return rc;
}
 
entropic_error_t entropic_user_message_queue_depth(
    entropic_handle_t handle, size_t* count) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!count) { return ENTROPIC_ERROR_INVALID_ARGUMENT; }
    *count = handle->engine
        ? handle->engine->user_message_queue_depth() : 0;
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_clear_user_message_queue(
    entropic_handle_t handle) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (handle->engine) {
        handle->engine->clear_user_message_queue();
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_set_queue_observer(
    entropic_handle_t handle,
    void (*observer)(const char*, size_t, void*),
    void* user_data) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    handle->queue_observer = observer;
    handle->queue_observer_data = user_data;
    if (handle->engine) {
        handle->engine->set_queue_observer(observer, user_data);
    }
    return ENTROPIC_OK;
}
 
// ── Conversation Context (v2.0.1) ────────────────────────────
 
entropic_error_t entropic_context_clear(entropic_handle_t handle) {
    if (!handle || !handle->engine) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    const auto key = handle->engine->active_session_key();
    handle->engine->clear_conversation();
    entropic::release_session_tool_state(handle, key);
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_context_get(
    entropic_handle_t handle, char** messages_json) {
    // gh#144 (v2.12.0): the !handle->engine leg is new — an unconfigured
    // handle has no engine, and this function dereferenced it. The siblings
    // entropic_context_clear and entropic_context_usage both guarded it;
    // this one and entropic_context_count did not. INVALID_HANDLE matches
    // those siblings' contract for an unconfigured handle.
    //
    // Ordering matters and is not the siblings': a NULL out-param on a
    // created-but-unconfigured handle must still report INVALID_ARGUMENT,
    // which v2.3.10 pinned. Folded into one exit for the returns <= 3 gate.
    if (!handle || !messages_json || !handle->engine) {
        return (handle != nullptr && messages_json == nullptr)
            ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    *messages_json = alloc_cstr(
        facade_json::serialize_messages(handle->engine->get_messages()));
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_run_session(
    entropic_handle_t handle,
    const char* session_key,
    const char* input,
    char** result_json) {
    entropic::HandleTurnGuard turn(handle, session_key);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !input || !result_json || !handle->engine
        || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!input || !result_json) ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : !handle->engine ? ENTROPIC_ERROR_INVALID_STATE
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    handle->engine->set_active_session(session_key ? session_key : "");
    try {
        auto result = handle->engine->run_turn(input);
        *result_json = alloc_cstr(
            facade_json::serialize_messages(result));
        if (handle->stream_observer != nullptr) {
            handle->stream_observer("", 0, handle->stream_observer_data);
        }
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_session: {}", handle->last_error);
        *result_json = nullptr;
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
entropic_error_t entropic_run_session_as(
    entropic_handle_t handle,
    const char* session_key,
    const char* tier_or_identity,
    const char* input,
    char** result_json) {
    entropic::HandleTurnGuard turn(handle, session_key);
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !tier_or_identity || !input || !result_json
        || !handle->engine || !turn.claim()) {
        return rc != ENTROPIC_OK ? rc
            : (!tier_or_identity || !input || !result_json)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : !handle->engine ? ENTROPIC_ERROR_INVALID_STATE
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    if (!handle->engine->has_tier(tier_or_identity)) {
        handle->last_error =
            std::string("unknown tier: ") + tier_or_identity;
        return ENTROPIC_ERROR_IDENTITY_NOT_FOUND;
    }
    handle->engine->set_active_session(session_key ? session_key : "");
    return run_as_inner(handle, tier_or_identity, input, result_json);
}
 
static entropic_error_t check_stream_args(
    entropic_handle_t handle, const char* tier, const char* input,
    void (*on_token)(const char*, size_t, void*)) {
    entropic_error_t rc = ENTROPIC_OK;
    if (!input || !on_token || !handle->engine) {
        rc = ENTROPIC_ERROR_INVALID_ARGUMENT;
    } else if (tier != nullptr && !handle->engine->has_tier(tier)) {
        handle->last_error = std::string("unknown tier: ") + tier;
        rc = ENTROPIC_ERROR_IDENTITY_NOT_FOUND;
    }
    return rc;
}
 
static entropic_error_t stream_session_turn(
    entropic_handle_t handle, const char* session_key, const std::string& tier,
    const char* input, void (*on_token)(const char*, size_t, void*),
    void* user_data, int* cancel_flag) {
    handle->engine->set_active_session(session_key ? session_key : "");
    try {
        int code = handle->engine->run_streaming(
            input, on_token, user_data, cancel_flag, tier);
        if (handle->stream_observer != nullptr) {
            handle->stream_observer("", 0, handle->stream_observer_data);
        }
        return code == 1 ? ENTROPIC_ERROR_CANCELLED : ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("run_session_streaming: {}", handle->last_error);
        return ENTROPIC_ERROR_GENERATE_FAILED;
    }
}
 
static entropic_error_t run_session_streaming_impl(
    entropic_handle_t handle, const char* session_key, const char* tier,
    const char* input, void (*on_token)(const char*, size_t, void*),
    void* user_data, int* cancel_flag) {
    entropic::HandleTurnGuard turn(handle, session_key);
    auto rc = check_orchestrator(handle);
    if (rc == ENTROPIC_OK) { rc = check_stream_args(handle, tier, input, on_token); }
    if (rc == ENTROPIC_OK && !turn.claim()) { rc = ENTROPIC_ERROR_ALREADY_RUNNING; }
    if (rc == ENTROPIC_OK) {
        rc = stream_session_turn(handle, session_key, tier ? tier : "",
                                 input, on_token, user_data, cancel_flag);
    }
    return rc;
}
 
entropic_error_t entropic_run_session_streaming(
    entropic_handle_t handle,
    const char* session_key,
    const char* input,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag) {
    return run_session_streaming_impl(handle, session_key, nullptr, input,
                                      on_token, user_data, cancel_flag);
}
 
entropic_error_t entropic_run_session_streaming_as(
    entropic_handle_t handle,
    const char* session_key,
    const char* tier_or_identity,
    const char* input,
    void (*on_token)(const char* token, size_t len, void* user_data),
    void* user_data,
    int* cancel_flag) {
    if (tier_or_identity == nullptr) { return ENTROPIC_ERROR_INVALID_ARGUMENT; }
    return run_session_streaming_impl(handle, session_key, tier_or_identity,
                                      input, on_token, user_data, cancel_flag);
}
 
entropic_error_t entropic_session_context_get(
    entropic_handle_t handle,
    const char* session_key,
    char** messages_json) {
    if (!handle || !messages_json || !handle->engine) {
        return (handle != nullptr && messages_json == nullptr)
            ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);
    *messages_json = alloc_cstr(facade_json::serialize_messages(
        handle->engine->messages_for(session_key ? session_key : "")));
    return ENTROPIC_OK;
}
 
static bool parse_restore_payload(entropic_handle_t handle,
                                  const char* messages_json,
                                  std::vector<entropic::Message>& out) {
    try {
        out = entropic::parse_messages_json(messages_json);
        return true;
    } catch (const std::exception& e) {
        handle->last_error =
            std::string("session_context_set: malformed messages JSON: ")
            + e.what();
        s_log->error("{}", handle->last_error);
        return false;
    }
}
 
static entropic_error_t session_context_set_inner(
    entropic_handle_t handle,
    const std::string& key,
    const char* messages_json) {
    std::vector<entropic::Message> msgs;
    if (!parse_restore_payload(handle, messages_json, msgs)) {
        return ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    if (!handle->engine->set_session_messages(key, std::move(msgs))) {
        handle->last_error =
            "session_context_set: a run on session '" + key
            + "' is in flight";
        return ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    // Whatever the old conversation left resident is now a prefix of a
    // history that no longer exists. Warm-keep would still be correct (it
    // matches TOKENS, and re-decodes the divergent tail), but the gate is
    // token equality rather than conversation identity — so the restore is
    // made correct by construction instead of by that argument.
    if (handle->orchestrator) {
        handle->orchestrator->forget_session_kv(key);
    }
    // gh#158: the reads and todos that described the replaced history
    // describe nothing now.
    entropic::release_session_tool_state(handle, key);
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_session_context_set(
    entropic_handle_t handle,
    const char* session_key,
    const char* messages_json) {
    if (!handle || !handle->engine || !messages_json) {
        return (handle != nullptr && handle->engine != nullptr)
            ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);
    return session_context_set_inner(
        handle, session_key != nullptr ? session_key : "", messages_json);
}
 
entropic_error_t entropic_session_context_count(
    entropic_handle_t handle,
    const char* session_key,
    size_t* count) {
    if (!handle || !count || !handle->engine) {
        return (handle != nullptr && count == nullptr)
            ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);
    *count = handle->engine->message_count_for(
        session_key ? session_key : "");
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_session_context_clear(
    entropic_handle_t handle,
    const char* session_key) {
    if (!handle || !handle->engine) {
        return ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);
    const std::string key = session_key ? session_key : "";
    handle->engine->clear_conversation_for(key);
    entropic::release_session_tool_state(handle, key);
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_session_drop(
    entropic_handle_t handle,
    const char* session_key) {
    if (!handle || !handle->engine) {
        return ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);
    const std::string key = session_key ? session_key : "";
    handle->engine->drop_session(key);
    entropic::release_session_tool_state(handle, key);
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_session_list(
    entropic_handle_t handle,
    char** sessions_json) {
    if (!handle || !sessions_json || !handle->engine) {
        return (handle != nullptr && sessions_json == nullptr)
            ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_INVALID_HANDLE;
    }
    entropic::HandleApiLock lock(handle);
    nlohmann::json arr = nlohmann::json::array();
    for (const auto& key : handle->engine->session_keys()) {
        arr.push_back({{"key", key},
                       {"messages", handle->engine->message_count_for(key)}});
    }
    *sessions_json = alloc_cstr(arr.dump());
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_context_count(
    entropic_handle_t handle, size_t* count) {
    // gh#144 (v2.12.0): see entropic_context_get — same missing engine
    // guard, same ordering constraint, same single-exit fold.
    if (!handle || !count || !handle->engine) {
        return (handle != nullptr && count == nullptr)
            ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_INVALID_HANDLE;
    }
    *count = handle->engine->message_count();
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_context_usage(
    entropic_handle_t handle,
    size_t* tokens_used,
    size_t* capacity) {
    if (!handle || !handle->engine) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!tokens_used || !capacity) { return ENTROPIC_ERROR_INVALID_ARGUMENT; }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    auto [used, max] = handle->engine->context_usage(
        handle->engine->get_messages());
    *tokens_used = static_cast<size_t>(used);
    *capacity = static_cast<size_t>(max);
    return max > 0 ? ENTROPIC_OK : ENTROPIC_ERROR_INVALID_STATE;
}
 
static entropic_error_t do_state_save(
    entropic_handle_t handle, const char* tier_name, const char* path) {
    if (!handle->orchestrator) { return ENTROPIC_ERROR_INVALID_STATE; }
    auto* backend = require_ready_backend(handle, tier_name);
    std::vector<uint8_t> buf;
    if (!backend->save_state(0, buf)) { return ENTROPIC_ERROR_INTERNAL; }
    std::ofstream out(path, std::ios::binary | std::ios::trunc);
    bool ok = out.is_open()
        && out.write(reinterpret_cast<const char*>(buf.data()),
                     static_cast<std::streamsize>(buf.size())).good();
    return ok ? ENTROPIC_OK : ENTROPIC_ERROR_IO;
}
 
entropic_error_t entropic_state_save(
    entropic_handle_t handle,
    const char* tier_name,
    const char* path) {
    // gh#157: this may now LOAD the tier's model. Claim the turn so the
    // load cannot land in the middle of a generation on another thread.
    entropic::HandleTurnGuard turn(handle);
    if (!handle || !tier_name || !path
        || (handle->engine != nullptr && !turn.claim())) {
        return !handle ? ENTROPIC_ERROR_INVALID_HANDLE
            : (!tier_name || !path) ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    entropic::HandleApiLock lock(handle);
    return c_api_try(handle,
        [&]() { return do_state_save(handle, tier_name, path); });
}
 
static bool read_state_file(const char* path, std::vector<uint8_t>& out_buf) {
    std::ifstream in(path, std::ios::binary | std::ios::ate);
    if (!in.is_open()) { return false; }
    auto sz = static_cast<std::streamsize>(in.tellg());
    if (sz <= 0) { return false; }
    in.seekg(0, std::ios::beg);
    out_buf.resize(static_cast<size_t>(sz));
    return static_cast<bool>(
        in.read(reinterpret_cast<char*>(out_buf.data()), sz));
}
 
static entropic_error_t do_state_load(
    entropic_handle_t handle, const char* tier_name, const char* path) {
    if (!handle->orchestrator) { return ENTROPIC_ERROR_INVALID_STATE; }
    auto* backend = require_ready_backend(handle, tier_name);
    std::vector<uint8_t> buf;
    if (!read_state_file(path, buf)) { return ENTROPIC_ERROR_IO; }
    return backend->restore_state(0, buf)
        ? ENTROPIC_OK : ENTROPIC_ERROR_INTERNAL;
}
 
entropic_error_t entropic_state_load(
    entropic_handle_t handle,
    const char* tier_name,
    const char* path) {
    // gh#157: may load the tier's model — see entropic_state_save.
    entropic::HandleTurnGuard turn(handle);
    if (!handle || !tier_name || !path
        || (handle->engine != nullptr && !turn.claim())) {
        return !handle ? ENTROPIC_ERROR_INVALID_HANDLE
            : (!tier_name || !path) ? ENTROPIC_ERROR_INVALID_ARGUMENT
            : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    entropic::HandleApiLock lock(handle);
    return c_api_try(handle,
        [&]() { return do_state_load(handle, tier_name, path); });
}
 
entropic_error_t entropic_metrics_json(
    entropic_handle_t handle, char** out) {
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!out) { return ENTROPIC_ERROR_INVALID_ARGUMENT; }
    *out = sp_get_metrics(handle);
    return ENTROPIC_OK;
}
 
// ── LoRA Adapter APIs (v1.9.2 → v2.0.0) ────────────────────
 
static entropic_error_t do_adapter_load(
    entropic_handle_t handle, const char* adapter_name,
    const char* adapter_path, const char* base_model_path, float scale)
{
    auto tier = handle->config.models.find_tier_by_path(base_model_path);
    if (tier.empty()) {
        throw std::runtime_error("no tier for model: "
            + std::string(base_model_path));
    }
    // gh#157: load the base model if it is not resident, rather than
    // returning INTERNAL "backend not ready" — which is what a deferred
    // (or released, gh#164) tier looks like.
    auto* base = handle->orchestrator->ensure_model(tier);
    auto* llama = dynamic_cast<entropic::LlamaCppBackend*>(base);
    if (!llama || !llama->llama_model_ptr()) {
        throw std::runtime_error("backend not ready for tier: " + tier);
    }
    bool ok = handle->orchestrator->adapter_manager().load(
        adapter_name, adapter_path, llama->llama_model_ptr(), scale);
    return ok ? ENTROPIC_OK : ENTROPIC_ERROR_ADAPTER_LOAD_FAILED;
}
 
entropic_error_t entropic_adapter_load(
    entropic_handle_t handle,
    const char* adapter_name,
    const char* adapter_path,
    const char* base_model_path,
    float scale)
{
    auto rc = check_orchestrator(handle);
    // gh#157: may load the base model — claim the turn first.
    entropic::HandleTurnGuard turn(handle);
    if (rc != ENTROPIC_OK || !adapter_name || !adapter_path
        || !base_model_path
        || (handle->engine != nullptr && !turn.claim())) {
        return rc != ENTROPIC_OK ? rc
            : (!adapter_name || !adapter_path || !base_model_path)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
                : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
    return c_api_try(handle, [&]() {
        return do_adapter_load(handle, adapter_name, adapter_path,
                               base_model_path, scale);
    });
}
 
entropic_error_t entropic_adapter_unload(
    entropic_handle_t handle,
    const char* adapter_name)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !adapter_name) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        auto& mgr = handle->orchestrator->adapter_manager();
        auto info = mgr.info(adapter_name);
        if (info.state == entropic::AdapterState::COLD) {
            throw std::runtime_error("adapter not loaded: "
                + std::string(adapter_name));
        }
        auto tier = handle->orchestrator->last_used_tier();
        auto* base = handle->orchestrator->get_backend(tier);
        auto* llama = dynamic_cast<entropic::LlamaCppBackend*>(base);
        mgr.unload(adapter_name, llama ? llama->llama_context_ptr() : nullptr);
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        return ENTROPIC_ERROR_INTERNAL;
    }
}
 
entropic_error_t entropic_adapter_swap(
    entropic_handle_t handle,
    const char* adapter_name)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !adapter_name) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        auto tier = handle->orchestrator->last_used_tier();
        auto* base = handle->orchestrator->get_backend(tier);
        auto* llama = dynamic_cast<entropic::LlamaCppBackend*>(base);
        if (!llama || !llama->llama_context_ptr()) {
            throw std::runtime_error("no active llama context for swap");
        }
        bool ok = handle->orchestrator->adapter_manager().swap(
            adapter_name, llama->llama_context_ptr());
        return ok ? ENTROPIC_OK : ENTROPIC_ERROR_ADAPTER_SWAP_FAILED;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        return ENTROPIC_ERROR_INTERNAL;
    }
}
 
int entropic_adapter_state(
    entropic_handle_t handle,
    const char* adapter_name)
{
    if (!handle || !handle->configured.load()
        || !handle->orchestrator || !adapter_name) {
        return -1;
    }
    try {
        auto st = handle->orchestrator->adapter_manager().state(adapter_name);
        return static_cast<int>(st);
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("adapter_state: {}", handle->last_error);
        return -1;
    }
}
 
char* entropic_adapter_info(
    entropic_handle_t handle,
    const char* adapter_name)
{
    if (!handle || !handle->configured.load()
        || !handle->orchestrator || !adapter_name) {
        return nullptr;
    }
    try {
        auto ai = handle->orchestrator->adapter_manager().info(adapter_name);
        return alloc_cstr(
            facade_json::serialize_adapter_info(ai).c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("adapter_info: {}", handle->last_error);
        return nullptr;
    }
}
 
char* entropic_adapter_list(entropic_handle_t handle)
{
    if (!handle || !handle->configured.load() || !handle->orchestrator) {
        return nullptr;
    }
    try {
        auto adapters = handle->orchestrator->adapter_manager().list_adapters();
        return alloc_cstr(
            facade_json::serialize_adapter_list(adapters).c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("adapter_list: {}", handle->last_error);
        return nullptr;
    }
}
 
// ── Grammar Registry APIs (v1.9.3 → v2.0.0) ────────────────
 
entropic_error_t entropic_grammar_register(
    entropic_handle_t handle,
    const char* key,
    const char* gbnf_content)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !key || !gbnf_content) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        bool ok = handle->orchestrator->grammar_registry()
            .register_grammar(key, gbnf_content);
        s_log->info("grammar_register: key={} ok={}", key, ok);
        return ok ? ENTROPIC_OK : ENTROPIC_ERROR_ALREADY_EXISTS;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("grammar_register: {}", handle->last_error);
        return ENTROPIC_ERROR_INTERNAL;
    }
}
 
entropic_error_t entropic_grammar_register_file(
    entropic_handle_t handle,
    const char* key,
    const char* path)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !key || !path) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        bool ok = handle->orchestrator->grammar_registry()
            .register_from_file(key, path);
        s_log->info("grammar_register_file: key={} ok={}", key, ok);
        return ok ? ENTROPIC_OK : ENTROPIC_ERROR_IO;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("grammar_register_file: {}", handle->last_error);
        return ENTROPIC_ERROR_INTERNAL;
    }
}
 
entropic_error_t entropic_grammar_deregister(
    entropic_handle_t handle,
    const char* key)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !key) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        bool ok = handle->orchestrator->grammar_registry().deregister(key);
        s_log->info("grammar_deregister: key={} ok={}", key, ok);
        return ok ? ENTROPIC_OK : ENTROPIC_ERROR_GRAMMAR_NOT_FOUND;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("grammar_deregister: {}", handle->last_error);
        return ENTROPIC_ERROR_INTERNAL;
    }
}
 
char* entropic_grammar_get(
    entropic_handle_t handle,
    const char* key)
{
    if (!handle || !handle->configured.load()
        || !handle->orchestrator || !key) {
        return nullptr;
    }
    try {
        auto content = handle->orchestrator->grammar_registry().get(key);
        return content.empty() ? nullptr : alloc_cstr(content.c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("grammar_get: {}", handle->last_error);
        return nullptr;
    }
}
 
char* entropic_grammar_validate(const char* gbnf_content) {
    if (!gbnf_content) { return alloc_cstr("null input"); }
    try {
        auto err = entropic::GrammarRegistry::validate(gbnf_content);
        return err.empty() ? nullptr : alloc_cstr(err.c_str());
    } catch (const std::exception& e) {
        return alloc_cstr(e.what());
    }
}
 
char* entropic_grammar_list(entropic_handle_t handle)
{
    if (!handle || !handle->configured.load() || !handle->orchestrator) {
        return nullptr;
    }
    try {
        auto entries = handle->orchestrator->grammar_registry().list();
        nlohmann::json arr = nlohmann::json::array();
        for (const auto& e : entries) {
            arr.push_back({{"key", e.key},
                           {"source", e.source},
                           {"validated", e.validated},
                           {"error", e.error}});
        }
        return alloc_cstr(arr.dump().c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("grammar_list: {}", handle->last_error);
        return nullptr;
    }
}
 
// ── GPU Resource Profile APIs (v1.9.7 → v2.0.0) ─────────────
 
entropic_error_t entropic_profile_register(
    entropic_handle_t handle,
    const char* profile_json)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !profile_json) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        auto j = nlohmann::json::parse(profile_json);
        entropic::GPUResourceProfile p;
        p.name = j.value("name", "");
        if (p.name.empty()) { throw std::invalid_argument("missing 'name'"); }
        p.n_batch = j.value("n_batch", 512);
        p.n_threads = j.value("n_threads", 0);
        p.n_threads_batch = j.value("n_threads_batch", 0);
        p.description = j.value("description", "");
        bool ok = handle->orchestrator->profile_registry()
            .register_profile(p);
        s_log->info("profile_register: name={} ok={}", p.name, ok);
        return ok ? ENTROPIC_OK : ENTROPIC_ERROR_ALREADY_EXISTS;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("profile_register: {}", handle->last_error);
        return ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
}
 
entropic_error_t entropic_profile_deregister(
    entropic_handle_t handle,
    const char* name)
{
    auto rc = check_orchestrator(handle);
    if (rc != ENTROPIC_OK || !name) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        bool ok = handle->orchestrator->profile_registry().deregister(name);
        s_log->info("profile_deregister: name={} ok={}", name, ok);
        return ok ? ENTROPIC_OK : ENTROPIC_ERROR_PROFILE_NOT_FOUND;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("profile_deregister: {}", handle->last_error);
        return ENTROPIC_ERROR_INTERNAL;
    }
}
 
char* entropic_profile_get(
    entropic_handle_t handle,
    const char* name)
{
    if (!handle || !handle->configured.load()
        || !handle->orchestrator || !name) {
        return nullptr;
    }
    try {
        auto p = handle->orchestrator->profile_registry().get(name);
        nlohmann::json j;
        j["name"] = p.name;
        j["n_batch"] = p.n_batch;
        j["n_threads"] = p.n_threads;
        j["n_threads_batch"] = p.n_threads_batch;
        j["description"] = p.description;
        return alloc_cstr(j.dump().c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("profile_get: {}", handle->last_error);
        return nullptr;
    }
}
 
char* entropic_profile_list(entropic_handle_t handle)
{
    if (!handle || !handle->configured.load() || !handle->orchestrator) {
        return nullptr;
    }
    try {
        auto names = handle->orchestrator->profile_registry().list();
        nlohmann::json arr = nlohmann::json(names);
        return alloc_cstr(arr.dump().c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("profile_list: {}", handle->last_error);
        return nullptr;
    }
}
 
// ── Throughput Query APIs (v1.9.7 → v2.0.0) ─────────────────
 
double entropic_throughput_tok_per_sec(
    entropic_handle_t handle,
    const char* model_path)
{
    (void)model_path;
    if (!handle || !handle->configured.load() || !handle->orchestrator) {
        return 0.0;
    }
    try {
        return handle->orchestrator->throughput_tracker().tok_per_sec();
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("throughput_tok_per_sec: {}", handle->last_error);
        return 0.0;
    }
}
 
void entropic_throughput_reset(
    entropic_handle_t handle,
    const char* model_path)
{
    (void)model_path;
    if (!handle || !handle->configured.load() || !handle->orchestrator) {
        return;
    }
    try {
        handle->orchestrator->throughput_tracker().reset();
        s_log->info("throughput_reset: data cleared");
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("throughput_reset: {}", handle->last_error);
    }
}
 
// ── MCP Authorization APIs (v1.9.4 → v2.0.0) ────────────────
 
entropic_error_t entropic_grant_mcp_key(
    entropic_handle_t handle,
    const char* identity_name,
    const char* pattern,
    entropic_mcp_access_level_t level)
{
    auto rc = check_mcp_auth(handle);
    if (rc != ENTROPIC_OK || !identity_name || !pattern) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    auto lvl = static_cast<entropic::MCPAccessLevel>(level);
    return handle->mcp_auth->grant(identity_name, pattern, lvl);
}
 
entropic_error_t entropic_revoke_mcp_key(
    entropic_handle_t handle,
    const char* identity_name,
    const char* pattern)
{
    auto rc = check_mcp_auth(handle);
    if (rc != ENTROPIC_OK || !identity_name || !pattern) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    return handle->mcp_auth->revoke(identity_name, pattern);
}
 
int entropic_check_mcp_key(
    entropic_handle_t handle,
    const char* identity_name,
    const char* tool_name,
    entropic_mcp_access_level_t level)
{
    if (!handle || !handle->configured.load()
        || !handle->mcp_auth || !identity_name || !tool_name) {
        return -1;
    }
    auto lvl = static_cast<entropic::MCPAccessLevel>(level);
    return handle->mcp_auth->check_access(identity_name, tool_name, lvl) ? 1 : 0;
}
 
char* entropic_list_mcp_keys(
    entropic_handle_t handle,
    const char* identity_name)
{
    if (!handle || !handle->configured.load()
        || !handle->mcp_auth || !identity_name) {
        return nullptr;
    }
    try {
        auto keys = handle->mcp_auth->list_keys(identity_name);
        nlohmann::json arr = nlohmann::json::array();
        for (const auto& k : keys) {
            arr.push_back({{"pattern", k.tool_pattern},
                           {"level", static_cast<int>(k.level)}});
        }
        return alloc_cstr(arr.dump().c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        return nullptr;
    }
}
 
entropic_error_t entropic_grant_mcp_key_from(
    entropic_handle_t handle,
    const char* granter,
    const char* grantee,
    const char* pattern,
    entropic_mcp_access_level_t level)
{
    auto rc = check_mcp_auth(handle);
    if (rc != ENTROPIC_OK || !granter || !grantee || !pattern) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    auto lvl = static_cast<entropic::MCPAccessLevel>(level);
    return handle->mcp_auth->grant_from(granter, grantee, pattern, lvl);
}
 
char* entropic_serialize_mcp_keys(entropic_handle_t handle)
{
    if (!handle || !handle->configured.load() || !handle->mcp_auth) {
        return nullptr;
    }
    try {
        auto json = handle->mcp_auth->serialize_all();
        return alloc_cstr(json.c_str());
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        return nullptr;
    }
}
 
entropic_error_t entropic_deserialize_mcp_keys(
    entropic_handle_t handle,
    const char* json)
{
    auto rc = check_mcp_auth(handle);
    if (rc != ENTROPIC_OK || !json) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    bool ok = handle->mcp_auth->deserialize_all(json);
    return ok ? ENTROPIC_OK : ENTROPIC_ERROR_INVALID_CONFIG;
}
 
// ── Dynamic Identity Management APIs (v1.9.6 → v2.0.0) ──────
 
entropic_error_t entropic_create_identity(
    entropic_handle_t handle,
    const char* config_json)
{
    auto rc = check_identity(handle);
    if (rc != ENTROPIC_OK || !config_json) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        auto j = nlohmann::json::parse(config_json);
        entropic::IdentityConfig cfg;
        cfg.name = j.value("name", "");
        cfg.system_prompt = j.value("system_prompt", "");
        if (j.contains("focus") && j["focus"].is_array()) {
            cfg.focus = j["focus"].get<std::vector<std::string>>();
        }
        cfg.origin = entropic::IdentityOrigin::DYNAMIC;
        return handle->identity_manager->create(cfg);
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        return ENTROPIC_ERROR_INVALID_CONFIG;
    }
}
 
entropic_error_t entropic_update_identity(
    entropic_handle_t handle,
    const char* name,
    const char* config_json)
{
    auto rc = check_identity(handle);
    if (rc != ENTROPIC_OK || !name || !config_json) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    try {
        auto j = nlohmann::json::parse(config_json);
        entropic::IdentityConfig cfg;
        cfg.name = name;
        cfg.system_prompt = j.value("system_prompt", "");
        if (j.contains("focus") && j["focus"].is_array()) {
            cfg.focus = j["focus"].get<std::vector<std::string>>();
        }
        cfg.origin = entropic::IdentityOrigin::DYNAMIC;
        return handle->identity_manager->update(name, cfg);
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        return ENTROPIC_ERROR_INVALID_CONFIG;
    }
}
 
entropic_error_t entropic_destroy_identity(
    entropic_handle_t handle,
    const char* name)
{
    auto rc = check_identity(handle);
    if (rc != ENTROPIC_OK || !name) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    return handle->identity_manager->destroy(name);
}
 
char* entropic_get_identity_config(
    entropic_handle_t handle,
    const char* name)
{
    if (!handle || !handle->identity_manager || !name) { return nullptr; }
    try {
        auto* cfg = handle->identity_manager->get(name);
        if (!cfg) { throw std::runtime_error("identity not found"); }
        nlohmann::json j;
        j["name"] = cfg->name;
        j["system_prompt"] = cfg->system_prompt;
        j["origin"] = (cfg->origin == entropic::IdentityOrigin::STATIC)
                       ? "static" : "dynamic";
        return alloc_cstr(j.dump().c_str());
    } catch (...) {
        return nullptr;
    }
}
 
char* entropic_list_identities(entropic_handle_t handle)
{
    if (!handle || !handle->identity_manager) { return nullptr; }
    try {
        auto names = handle->identity_manager->list();
        nlohmann::json arr(names);
        return alloc_cstr(arr.dump().c_str());
    } catch (...) {
        return nullptr;
    }
}
 
entropic_error_t entropic_identity_count(
    entropic_handle_t handle,
    size_t* total,
    size_t* dynamic)
{
    auto rc = check_identity(handle);
    if (rc != ENTROPIC_OK || !total) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    *total = handle->identity_manager->count();
    if (dynamic) { *dynamic = handle->identity_manager->count_dynamic(); }
    return ENTROPIC_OK;
}
 
// ── Log-Probability Evaluation APIs (v1.9.10 → v2.0.0) ──────
 
static void fill_logprob_result(const entropic::LogprobResult& lr,
                                entropic_logprob_result_t* result) {
    result->n_tokens = lr.n_tokens;
    result->n_logprobs = lr.n_logprobs;
    result->perplexity = lr.perplexity;
    result->total_logprob = lr.total_logprob;
    result->logprobs = static_cast<float*>(
        malloc(sizeof(float) * lr.logprobs.size()));
    std::copy(lr.logprobs.begin(), lr.logprobs.end(), result->logprobs);
    result->tokens = static_cast<int32_t*>(
        malloc(sizeof(int32_t) * lr.tokens.size()));
    std::copy(lr.tokens.begin(), lr.tokens.end(), result->tokens);
}
 
entropic_error_t entropic_get_logprobs(
    entropic_handle_t handle,
    const char* model_id,
    const int32_t* tokens,
    int n_tokens,
    entropic_logprob_result_t* result)
{
    auto rc = check_orchestrator(handle);
    // gh#157: may load the tier's model — claim the turn first.
    entropic::HandleTurnGuard turn(handle);
    if (rc != ENTROPIC_OK || !model_id || !tokens || !result || n_tokens < 2
        || (handle->engine != nullptr && !turn.claim())) {
        return rc != ENTROPIC_OK ? rc
            : (!model_id || !tokens || !result || n_tokens < 2)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
                : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        auto* backend = require_ready_backend(handle, model_id);
        fill_logprob_result(backend->evaluate_logprobs(tokens, n_tokens),
                            result);
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("get_logprobs: {}", handle->last_error);
        return ENTROPIC_ERROR_EVAL_FAILED;
    }
}
 
entropic_error_t entropic_compute_perplexity(
    entropic_handle_t handle,
    const char* model_id,
    const int32_t* tokens,
    int n_tokens,
    float* perplexity)
{
    auto rc = check_orchestrator(handle);
    // gh#157: may load the tier's model — claim the turn first.
    entropic::HandleTurnGuard turn(handle);
    if (rc != ENTROPIC_OK || !model_id || !tokens || !perplexity
        || n_tokens < 2 || (handle->engine != nullptr && !turn.claim())) {
        return rc != ENTROPIC_OK ? rc
            : (!model_id || !tokens || !perplexity || n_tokens < 2)
                ? ENTROPIC_ERROR_INVALID_ARGUMENT
                : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    try {
        entropic::HandleApiLock lock(handle);  // gh#59 v2.3.1: mutex + log scope
        auto* backend = require_ready_backend(handle, model_id);
        *perplexity = backend->compute_perplexity(tokens, n_tokens);
        return ENTROPIC_OK;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("compute_perplexity: {}", handle->last_error);
        return ENTROPIC_ERROR_EVAL_FAILED;
    }
}
 
void entropic_free_logprob_result(entropic_logprob_result_t* result)
{
    if (result == nullptr) {
        return;
    }
    free(result->logprobs);
    result->logprobs = nullptr;
    free(result->tokens);
    result->tokens = nullptr;
}
 
// ── Vision Query API (v1.9.11 → v2.0.0) ─────────────────────
 
int entropic_model_has_vision(
    entropic_handle_t handle,
    const char* model_id)
{
    if (!handle || !handle->configured.load()
        || !handle->orchestrator || !model_id) {
        return 0;
    }
    try {
        // gh#157: answer from CONFIG, not from the backend. The backend's
        // has_vision_ is set while the mmproj context is built during
        // ACTIVATION, so an unloaded tier answered 0 — wrong, not unknown —
        // and with models.defer_load unloaded is the normal state.
        return handle->orchestrator->tier_declares_vision(model_id) ? 1 : 0;
    } catch (const std::exception& e) {
        handle->last_error = e.what();
        s_log->error("model_has_vision: {}", handle->last_error);
        return 0;
    }
}
 
// ── Constitutional Validation APIs (v1.9.8 → v2.0.0) ────────
 
entropic_error_t entropic_validation_set_enabled(
    entropic_handle_t handle,
    bool enabled)
{
    if (!handle) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    if (!handle->validator) { return ENTROPIC_ERROR_INVALID_STATE; }
    handle->validator->set_global_enabled(enabled);
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_validation_set_identity(
    entropic_handle_t handle,
    const char* identity_name,
    bool enabled)
{
    if (!handle || !handle->validator) {
        return !handle ? ENTROPIC_ERROR_INVALID_HANDLE
                       : ENTROPIC_ERROR_INVALID_STATE;
    }
    if (!identity_name) { return ENTROPIC_ERROR_INVALID_ARGUMENT; }
    handle->validator->set_identity_validation(identity_name, enabled);
    return ENTROPIC_OK;
}
 
char* entropic_validation_last_result(entropic_handle_t handle)
{
    if (!handle || !handle->validator) { return nullptr; }
    try {
        auto result = handle->validator->last_result();
        nlohmann::json j;
        j["content"] = entropic::mcp::sanitize_utf8(result.content);
        j["was_revised"] = result.was_revised;
        j["revision_count"] = result.revision_count;
        return alloc_cstr(j.dump().c_str());
    } catch (...) {
        return nullptr;
    }
}
 
entropic_error_t entropic_get_diagnostic_prompt(
    entropic_handle_t handle,
    char** prompt_out) {
    if (handle == nullptr || prompt_out == nullptr) {
        return ENTROPIC_ERROR_INVALID_ARGUMENT;
    }
    (void)handle;
    static const char* prompt =
        "[SYSTEM DIRECTIVE: SELF-DIAGNOSIS]\n\n"
        "Analyze your recent actions and identify any issues. "
        "Follow these steps:\n\n"
        "1. Call entropic.diagnose to get a full engine state "
        "snapshot.\n"
        "2. Review the tool call history for:\n"
        "   - Repeated failures (same tool, same error)\n"
        "   - Duplicate tool calls (circuit breaker risk)\n"
        "   - Tool calls that returned errors\n"
        "   - Unexpected state (wrong phase, wrong tier)\n"
        "3. Review your reasoning for:\n"
        "   - Actions that didn't achieve the stated goal\n"
        "   - Unnecessary tool calls\n"
        "   - Missing context that led to errors\n"
        "4. Produce a structured assessment:\n"
        "   - FINDINGS: What went wrong (be specific)\n"
        "   - ROOT CAUSE: Why it went wrong\n"
        "   - RECOMMENDATION: What to do differently\n\n"
        "Be honest and specific. The goal is accurate "
        "self-assessment, not self-defense.\n";
    *prompt_out = alloc_cstr(prompt);
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_speculative_compat(
    entropic_handle_t handle,
    int* compatible,
    char** diagnostic) {
    if (handle == nullptr || compatible == nullptr) {
        return ENTROPIC_ERROR_INVALID_HANDLE;
    }
    if (!handle->orchestrator) {
        return ENTROPIC_ERROR_INVALID_STATE;
    }
    auto info = handle->orchestrator->check_speculative_compat();
    *compatible = info.compatible ? 1 : 0;
    if (diagnostic != nullptr) {
        *diagnostic = info.compatible
                          ? nullptr
                          : alloc_cstr(info.diagnostic);
    }
    return ENTROPIC_OK;
}
 
/* ── VRAM-aware tier residency (v2.2.4, gh#57) ─────────── */
 
entropic_error_t entropic_set_residency_observer(
    entropic_handle_t handle,
    entropic_residency_observer_t observer,
    void* user_data) {
    if (handle == nullptr) { return ENTROPIC_ERROR_INVALID_HANDLE; }
    // Engine-not-configured (no orchestrator yet) and observer==nullptr
    // both collapse to a no-op set: pre-configure registration is
    // ignored (consumers must re-register after configure_*), and
    // an explicit nullptr clears any prior slot. Done as one branch
    // to stay under the knots return-count gate.
    entropic::ModelOrchestrator::ResidencyObserverFn fn;
    if (observer != nullptr) {
        fn = [observer, user_data](
            entropic::ModelOrchestrator::ResidencyEvent event,
            const std::string& tier_name,
            const std::string& model_path,
            size_t footprint) {
            observer(static_cast<entropic_residency_event_t>(event),
                     tier_name.c_str(),
                     model_path.c_str(),
                     footprint,
                     user_data);
        };
    }
    if (handle->orchestrator) {
        handle->orchestrator->set_residency_observer(std::move(fn));
    }
    return ENTROPIC_OK;
}
 
entropic_error_t entropic_release_model(
    entropic_handle_t handle,
    const char* tier_name) {
    auto rc = check_orchestrator(handle);
    entropic::HandleTurnGuard turn(handle);
    if (rc != ENTROPIC_OK
        || (handle->engine != nullptr && !turn.claim())) {
        return rc != ENTROPIC_OK ? rc : ENTROPIC_ERROR_ALREADY_RUNNING;
    }
    entropic::HandleApiLock lock(handle);
    return c_api_try(handle, [&]() {
        return handle->orchestrator->release_models(
            tier_name != nullptr ? tier_name : "");
    });
}
 
entropic_error_t entropic_residency_snapshot(
    entropic_handle_t handle,
    char** out_json) {
    entropic_error_t rc = ENTROPIC_OK;
    if (handle == nullptr || out_json == nullptr) {
        rc = ENTROPIC_ERROR_INVALID_HANDLE;
    } else if (!handle->orchestrator) {
        rc = ENTROPIC_ERROR_INVALID_STATE;
    } else {
        std::string snapshot =
            handle->orchestrator->residency_snapshot_json();
        *out_json = alloc_cstr(snapshot);
        if (*out_json == nullptr) {
            rc = ENTROPIC_ERROR_OUT_OF_MEMORY;
        }
    }
    return rc;
}
 
} // extern "C"