loader.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include <entropic/config/loader.h>
#include <entropic/config/validate.h>
#include <entropic/types/logging.h>
#include "yaml_util.h"
 
#include <nlohmann/json.hpp>
 
#include <algorithm>
#include <fstream>
#include <optional>
#include <sstream>
 
#include <dlfcn.h>
 
static auto s_log = entropic::log::get("config");
 
namespace entropic::config {
 
static void parse_model_runtime_knobs(
    ryml::ConstNodeRef node, ModelConfig& config)
{
    extract(node, "cache_type_k", config.cache_type_k);
    extract(node, "cache_type_v", config.cache_type_v);
    extract(node, "n_batch", config.n_batch);
    extract(node, "n_ubatch", config.n_ubatch);  // gh#23 v2.3.17
    extract(node, "n_threads", config.n_threads);
    extract(node, "tensor_split", config.tensor_split);
    extract(node, "split_mode", config.split_mode);  // gh#23 v2.3.18
    extract(node, "main_gpu", config.main_gpu);      // gh#23 v2.3.19
    extract(node, "offload_kqv", config.offload_kqv); // gh#23 v2.3.20
    extract(node, "rope_freq_base", config.rope_freq_base); // gh#23 v2.3.21
    extract(node, "rope_freq_scale", config.rope_freq_scale); // gh#23 v2.3.22
    extract(node, "n_parallel", config.n_parallel); // gh#23 v2.3.23
    extract(node, "max_sessions", config.max_sessions); // gh#144 v2.12.0
    // gh#153 #42(iii) (v2.13.0, EXPERIMENTAL): expert-tensor offload.
    // Absent leaves the struct default 0 — no overrides, byte-identical.
    extract(node, "cpu_moe_layers", config.cpu_moe_layers);
    extract(node, "flash_attn", config.flash_attn);
}
 
static void parse_sampler_overrides(
    ryml::ConstNodeRef node, TierConfig& config)
{
    float f = 0.0f;
    int i = 0;
    bool b = false;
    std::string s;
    if (extract(node, "temperature", f))       { config.temperature = f; }
    if (extract(node, "top_p", f))             { config.top_p = f; }
    if (extract(node, "min_p", f))             { config.min_p = f; }
    if (extract(node, "presence_penalty", f))  { config.presence_penalty = f; }
    if (extract(node, "frequency_penalty", f)) { config.frequency_penalty = f; }
    if (extract(node, "repeat_penalty", f))    { config.repeat_penalty = f; }
    if (extract(node, "top_k", i))             { config.top_k = i; }
    if (extract(node, "max_output_tokens", i)) { config.max_output_tokens = i; }
    if (extract(node, "enable_thinking", b))   { config.enable_thinking = b; }
    if (extract(node, "tool_call_mode", s))    { config.tool_call_mode = s; }  // gh#103
}
 
static void parse_tier_speculative_override(
    ryml::ConstNodeRef node, TierConfig& config)
{
    if (!node.has_child("speculative")) { return; }
    auto spec = node["speculative"];
    bool mtp = false;
    if (extract(spec, "mtp", mtp)) { config.speculative_mtp = mtp; }
}
 
static std::string resolve_model_path(
    ryml::ConstNodeRef node,
    const BundledModels& registry,
    ModelConfig& config)
{
    std::string path_str;
    if (extract(node, "path", path_str)) {
        config.path = registry.resolve(path_str);
        return "";
    }
 
    std::string family;
    std::string size;
    std::string quant;
    const bool hf = extract(node, "family", family);
    const bool hs = extract(node, "size", size);
    const bool hq = extract(node, "quant", quant);
    if (!hf && !hs && !hq) { return ""; }  // no path, no selector
 
    // Single-exit accumulator (knots returns gate ≤ 3).
    std::string err;
    if (!(hf && hs && hq)) {
        err = "model selector requires all of family/size/quant "
              "(or use path:)";
    } else if (const std::string key = registry.find_by(family, size, quant);
               key.empty()) {
        err = "no bundled model matches family=" + family
              + " size=" + size + " quant=" + quant;
    } else {
        config.path = registry.resolve(key);
    }
    return err;
}
 
static void parse_gpu_layers(ryml::ConstNodeRef node, ModelConfig& config) {
    std::string raw;
    if (extract(node, "gpu_layers", raw) && raw == "auto") {
        config.gpu_layers_auto = true;
        return;
    }
    extract(node, "gpu_layers", config.gpu_layers);
}
 
static std::string parse_model_config(
    ryml::ConstNodeRef node,
    const BundledModels& registry,
    ModelConfig& config)
{
    const std::string err = resolve_model_path(node, registry, config);
    if (!err.empty()) { return err; }
 
    extract(node, "adapter", config.adapter);
    extract(node, "context_length", config.context_length);
    parse_gpu_layers(node, config);
    extract(node, "keep_warm", config.keep_warm);
    extract(node, "use_mlock", config.use_mlock);
    extract(node, "reasoning_budget", config.reasoning_budget);
    parse_model_runtime_knobs(node, config);
    extract_string_list_opt(node, "allowed_tools", config.allowed_tools);
 
    /* v1.9.11 mmproj wiring at the loader (gh#42, gh#41): read mmproj
     * here so the YAML key matches the bundled_models.yaml registry
     * shape and the orchestrator can declare a tier vision-capable. */
    std::string mmproj_str;
    if (extract(node, "mmproj", mmproj_str)) {
        config.mmproj_path = registry.resolve(mmproj_str);
    }
 
    return "";
}
 
static std::string parse_tier_config(
    ryml::ConstNodeRef node,
    const BundledModels& registry,
    TierConfig& config)
{
    auto err = parse_model_config(node, registry, config);
    if (!err.empty()) {
        return err;
    }
 
    // gh#94 (v2.7.3): per-tier sampler overrides live on TierConfig.
    parse_sampler_overrides(node, config);
 
    // gh#108 (v2.9.4): per-tier speculative.mtp override.
    parse_tier_speculative_override(node, config);
 
    extract_tri_state_path(node, "identity",
                           config.identity, config.identity_disabled);
 
    std::string grammar_str;
    if (extract(node, "grammar", grammar_str)) {
        config.grammar = expand_home(std::filesystem::path(grammar_str));
    }
 
    // gh#134 (v2.10.4): opt a mandatory-tool tier into eager tool-call
    // grammar enforcement. Optional so an unset tier inherits AUTO.
    bool require_tc = false;
    if (extract(node, "require_tool_call", require_tc)) {
        config.require_tool_call = require_tc;
    }
 
    std::string auto_chain_str;
    if (extract(node, "auto_chain", auto_chain_str)) {
        config.auto_chain = auto_chain_str;
    }
 
    bool routable_val = false;
    if (extract(node, "routable", routable_val)) {
        config.routable = routable_val;
    }
 
    // gh#162 (v2.13.0): a tier may declare that a contextless delegation
    // to it is refused at the tool boundary.
    extract(node, "requires_context", config.requires_context);
 
    /* gh#41 v2.1.8: tier capabilities. Missing key → ["text"] so
     * every pre-v2.1.8 tier config remains valid. Configs that
     * declare capabilities explicitly must include "text" themselves
     * if the tier still serves text — we don't auto-inject. */
    if (!extract_string_list(node, "capabilities", config.capabilities)) {
        config.capabilities = {"text"};
    }
 
    return "";
}
 
static std::string parse_models_config(
    ryml::ConstNodeRef node,
    const BundledModels& registry,
    ModelsConfig& config)
{
    extract(node, "default", config.default_tier);
    // gh#157 (v2.13.0): opt-in lazy load of the default tier.
    extract(node, "defer_load", config.defer_load);
 
    if (node.has_child("router")) {
        config.router.emplace();
        auto err = parse_model_config(node["router"], registry,
                                      *config.router);
        if (!err.empty()) {
            return "models.router: " + err;
        }
    }
 
    for (auto child : node) {
        std::string key = to_string(child.key());
        if (key == "default" || key == "router" || key == "defer_load") {
            continue;
        }
        if (!child.is_map()) {
            continue;
        }
 
        TierConfig tier;
        if (config.tiers.count(key) > 0) {
            tier = config.tiers[key];
        }
        auto err = parse_tier_config(child, registry, tier);
        if (!err.empty()) {
            return "models." + key + ": " + err;
        }
        config.tiers[key] = std::move(tier);
    }
 
    return "";
}
 
static std::string parse_routing_config(
    ryml::ConstNodeRef node,
    RoutingConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "fallback_tier", config.fallback_tier);
 
    std::string class_prompt;
    if (extract(node, "classification_prompt", class_prompt)) {
        config.classification_prompt = class_prompt;
    }
 
    extract_string_map(node, "tier_map", config.tier_map);
    extract_string_list_map(node, "handoff_rules", config.handoff_rules);
 
    return "";
}
 
static std::string parse_compaction_config(
    ryml::ConstNodeRef node,
    CompactionConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "threshold_percent", config.threshold_percent);
    extract(node, "preserve_recent_turns", config.preserve_recent_turns);
    extract(node, "summary_max_tokens", config.summary_max_tokens);
    extract(node, "notify_user", config.notify_user);
    extract(node, "save_full_history", config.save_full_history);
    extract(node, "tool_result_ttl", config.tool_result_ttl);
    extract(node, "warning_threshold_percent",
            config.warning_threshold_percent);
    return "";
}
 
static std::string parse_delegation_config(
    ryml::ConstNodeRef node,
    DelegationConfig& config)
{
    std::string mode;
    extract(node, "isolation", mode);
    if (mode.empty() || mode == "none") {
        config.isolation = DelegationIsolation::none;
    } else if (mode == "sandbox") {
        config.isolation = DelegationIsolation::sandbox;
    } else {
        return "delegation.isolation: unknown mode '" + mode +
               "' (expected 'none' or 'sandbox')";
    }
    return "";
}
 
static std::string parse_permissions_config(
    ryml::ConstNodeRef node,
    PermissionsConfig& config)
{
    extract_string_list(node, "allow", config.allow);
    extract_string_list(node, "deny", config.deny);
    extract(node, "auto_approve", config.auto_approve);
    return "";
}
 
static std::string parse_outside_root_access(
    ryml::ConstNodeRef node,
    FilesystemConfig& config)
{
    std::string raw;
    if (!extract(node, "allow_outside_root", raw)) { return ""; }
    static const std::vector<std::string> yes = {
        "true", "True", "TRUE", "yes", "Yes", "YES", "on", "On", "ON", "1"};
    static const std::vector<std::string> no = {
        "false", "False", "FALSE", "no", "No", "NO", "off", "Off", "OFF",
        "0"};
    std::string err;
    if (std::find(yes.begin(), yes.end(), raw) != yes.end()) {
        config.allow_outside_root = OutsideRootAccess::allow;
    } else if (std::find(no.begin(), no.end(), raw) != no.end()) {
        config.allow_outside_root = OutsideRootAccess::refuse;
    } else if (raw == "optional") {
        config.allow_outside_root = OutsideRootAccess::optional;
    } else {
        err = "mcp.filesystem.allow_outside_root: unknown value '" + raw
            + "' (expected true, false or optional)";
    }
    return err;
}
 
static std::string parse_outside_root_list(
    ryml::ConstNodeRef node,
    c4::csubstr key,
    std::vector<std::filesystem::path>& out)
{
    std::vector<std::string> raw;
    if (!extract_string_list(node, key, raw)) { return ""; }
    std::vector<std::filesystem::path> paths;
    std::string err;
    for (const auto& entry : raw) {
        auto p = expand_home(std::filesystem::path(entry));
        if (!p.is_absolute() && err.empty()) {
            err = "mcp.filesystem." + to_string(key) + ": entry '" + entry
                + "' is not an absolute path";
        }
        paths.push_back(std::move(p));
    }
    if (err.empty()) { out = std::move(paths); }
    return err;
}
 
static std::string parse_filesystem_config(
    ryml::ConstNodeRef node,
    FilesystemConfig& config)
{
    extract(node, "diagnostics_on_edit", config.diagnostics_on_edit);
    extract(node, "fail_on_errors", config.fail_on_errors);
    extract(node, "diagnostics_timeout", config.diagnostics_timeout);
    extract(node, "max_read_context_pct", config.max_read_context_pct);
    extract(node, "max_walk_entries", config.max_walk_entries);
 
    int max_read = 0;
    if (extract(node, "max_read_bytes", max_read)) {
        config.max_read_bytes = max_read;
    }
 
    auto err = parse_outside_root_access(node, config);
    if (err.empty()) {
        err = parse_outside_root_list(node, "outside_root_allow",
                                      config.outside_root_allow);
    }
    if (err.empty()) {
        err = parse_outside_root_list(node, "outside_root_deny",
                                      config.outside_root_deny);
    }
    return err;
}
 
static void parse_tool_descriptions(
    ryml::ConstNodeRef node,
    ExternalMCPConfig& config)
{
    if (!node.is_map()) {
        return;
    }
    for (auto child : node) {
        if (!child.has_key() || !child.has_val() || child.val_is_null()) {
            continue;
        }
        config.tool_descriptions[to_string(child.key())] =
            to_string(child.val());
    }
}
 
static std::string parse_external_mcp_config(
    ryml::ConstNodeRef node,
    ExternalMCPConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "rate_limit", config.rate_limit);
    extract(node, "ask_streaming", config.ask_streaming);
    // gh#204 (v2.14.0): range-checked where it is used — the listener fails
    // configure loudly on a bad port rather than this parse dropping it.
    extract(node, "http_port", config.http_port);
    // gh#145: consumer-owned identity. Both default to "entropic", so an
    // unset config advertises exactly the pre-2.12.0 names.
    extract(node, "tool_prefix", config.tool_prefix);
    extract(node, "server_name", config.server_name);
 
    if (node.is_map() && node.has_child("socket_path")
        && !node["socket_path"].val_is_null()) {
        std::filesystem::path tmp;
        extract_path(node, "socket_path", tmp);
        config.socket_path = tmp;
    }
 
    if (node.is_map() && node.has_child("tool_descriptions")) {
        parse_tool_descriptions(node["tool_descriptions"], config);
    }
 
    return "";
}
 
static std::string parse_bash_config(
    ryml::ConstNodeRef node,
    BashConfig& config)
{
    int timeout = config.timeout_seconds;
    std::string err;
    if (extract(node, "timeout_seconds", timeout) && timeout < 1) {
        err = "mcp.bash.timeout_seconds: must be a positive number of "
              "seconds, got " + std::to_string(timeout);
    } else {
        config.timeout_seconds = timeout;
    }
    return err;
}
 
static ExternalServerEntry parse_external_server_entry(ryml::ConstNodeRef node) {
    ExternalServerEntry entry;
    extract(node, "command", entry.command);
    extract(node, "url", entry.url);
    extract_string_list(node, "args", entry.args);
    if (node.has_child("env") && node["env"].is_map()) {
        for (auto kv : node["env"]) {
            if (kv.has_key() && kv.has_val()) {
                entry.env[to_string(kv.key())] = to_string(kv.val());
            }
        }
    }
    return entry;
}
 
static std::string parse_external_servers(ryml::ConstNodeRef node,
                                          MCPConfig& config) {
    if (!node.has_child("external_servers")) { return ""; }
    auto servers = node["external_servers"];
    if (!servers.is_map()) {
        return "mcp.external_servers: must be a map of name -> server";
    }
    std::string err;
    for (auto child : servers) {
        const std::string name = to_string(child.key());
        auto entry = parse_external_server_entry(child);
        if (entry.command.empty() && entry.url.empty()) {
            err = "mcp.external_servers." + name + ": needs `command` or `url`";
            break;
        }
        config.external_servers[name] = std::move(entry);
    }
    return err;
}
 
static void parse_mcpjson_enablement(ryml::ConstNodeRef node,
                                     MCPConfig& config) {
    extract_string_list(node, "enabled_mcpjson_servers",
                        config.enabled_mcpjson_servers);
    extract_string_list(node, "disabled_mcpjson_servers",
                        config.disabled_mcpjson_servers);
    extract(node, "enable_all_project_mcp_servers",
            config.enable_all_project_mcp_servers);
}
 
static std::string validate_server_timeout(const MCPConfig& config) {
    std::string err;
    if (config.server_timeout_seconds < 1) {
        err = "mcp.server_timeout_seconds: must be a positive number of "
              "seconds, got " + std::to_string(config.server_timeout_seconds);
    }
    return err;
}
 
static std::string parse_mcp_sections(
    ryml::ConstNodeRef node,
    MCPConfig& config)
{
    std::string err;
    if (node.has_child("filesystem")) {
        err = parse_filesystem_config(node["filesystem"], config.filesystem);
    }
    if (err.empty() && node.has_child("bash")) {
        err = parse_bash_config(node["bash"], config.bash);
    }
    if (node.has_child("external")) {
        parse_external_mcp_config(node["external"], config.external);
    }
    parse_mcpjson_enablement(node, config);
    if (err.empty()) { err = parse_external_servers(node, config); }
    return err;
}
 
static std::string parse_mcp_config(
    ryml::ConstNodeRef node,
    MCPConfig& config)
{
    extract(node, "enable_entropic", config.enable_entropic);
    extract(node, "enable_filesystem", config.enable_filesystem);
    extract(node, "enable_bash", config.enable_bash);
    extract(node, "enable_git", config.enable_git);
    extract(node, "enable_diagnostics", config.enable_diagnostics);
    extract(node, "enable_web", config.enable_web);
    extract(node, "server_timeout_seconds", config.server_timeout_seconds);
    extract(node, "working_dir", config.working_dir);
 
    // gh#133 (v2.10.1): mcp.plugins — dlopen-loaded in-process server .so
    // paths. expand_home so `~/...` works like every other path key.
    std::vector<std::string> plugin_paths;
    if (extract_string_list(node, "plugins", plugin_paths)) {
        config.plugins.clear();
        for (const auto& p : plugin_paths) {
            config.plugins.push_back(expand_home(std::filesystem::path(p)));
        }
    }
    auto err = parse_mcp_sections(node, config);
    return err.empty() ? validate_server_timeout(config) : err;
}
 
static std::string parse_generation_config(
    ryml::ConstNodeRef node,
    GenerationConfig& config)
{
    extract(node, "max_tokens", config.max_tokens);
    extract(node, "default_temperature", config.default_temperature);
    extract(node, "default_top_p", config.default_top_p);
    // gh#80 (v2.5.0): thinking-budget knobs (validated in build_loop_config).
    extract(node, "budget_mode", config.budget_mode);
    extract(node, "budget_limit", config.budget_limit);
    // gh#110 (v2.9.6): batch vs streaming agent-loop delivery mode.
    extract(node, "stream_output", config.stream_output);
    return "";
}
 
static std::string parse_lsp_config(
    ryml::ConstNodeRef node,
    LSPConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "python_enabled", config.python_enabled);
    extract(node, "c_enabled", config.c_enabled);
    return "";
}
 
static std::string parse_prompt_cache_config(
    ryml::ConstNodeRef node,
    PromptCacheConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "log_hits", config.log_hits);
 
    int max_bytes_int = 0;
    if (extract(node, "max_bytes", max_bytes_int)) {
        config.max_bytes = static_cast<size_t>(max_bytes_int);
    }
 
    return "";
}
 
static void parse_constitutional_validation_config(
    ryml::ConstNodeRef node,
    ConstitutionalValidationConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "max_revisions", config.max_revisions);
    extract(node, "max_critique_tokens", config.max_critique_tokens);
    extract(node, "temperature", config.temperature);
    extract(node, "enable_thinking", config.enable_thinking);
    extract(node, "priority", config.priority);
    extract(node, "grammar_key", config.grammar_key);
    extract_string_list(node, "skip_tiers", config.skip_tiers);
}
 
static void parse_speculative_config(
    ryml::ConstNodeRef node,
    const BundledModels& registry,
    SpeculativeConfig& config)
{
    extract(node, "enabled", config.enabled);
    extract(node, "n_draft", config.n_draft);
    extract(node, "mtp", config.mtp);  // gh#106: drive the MTP head path
    // Nested ModelConfig — every llama.cpp knob is consumer-tunable
    // via `inference.speculative.draft.<field>`. Defaults come from
    // `make_default_draft_model_config()` (gpu_layers=0, flash_attn=
    // false, context_length=8192, n_threads=4). (v2.1.11)
    if (node.has_child("draft")) {
        auto err = parse_model_config(
            node["draft"], registry, config.draft);
        if (!err.empty()) {
            s_log->warn("inference.speculative.draft parse: {}", err);
        }
    }
}
 
static void parse_inference_subsections(
    ryml::ConstNodeRef root,
    const BundledModels& registry,
    ParsedConfig& config)
{
    if (!root.has_child("inference")) { return; }
    auto inf = root["inference"];
    if (inf.has_child("prompt_cache"))
        parse_prompt_cache_config(inf["prompt_cache"], config.prompt_cache);
    if (inf.has_child("speculative"))
        parse_speculative_config(inf["speculative"], registry,
                                 config.inference.speculative);
}
 
static std::string parse_optional_subsections(
    ryml::ConstNodeRef root,
    const BundledModels& registry,
    ParsedConfig& config)
{
    std::string err;
    if (root.has_child("generation"))
        parse_generation_config(root["generation"], config.generation);
    if (root.has_child("permissions"))
        parse_permissions_config(root["permissions"], config.permissions);
    if (root.has_child("mcp"))
        err = parse_mcp_config(root["mcp"], config.mcp);
    if (root.has_child("compaction"))
        parse_compaction_config(root["compaction"], config.compaction);
    if (root.has_child("lsp"))
        parse_lsp_config(root["lsp"], config.lsp);
    parse_inference_subsections(root, registry, config);
    if (root.has_child("constitutional_validation"))
        parse_constitutional_validation_config(
            root["constitutional_validation"],
            config.constitutional_validation);
    return err;
}
 
static void extract_scalar_fields(ryml::ConstNodeRef root,
                                  ParsedConfig& config)
{
    extract(root, "log_level", config.log_level);
    extract(root, "inject_model_context", config.inject_model_context);
    // gh#158 (v2.13.0): opt-in per-session-key run concurrency.
    extract(root, "concurrent_sessions", config.concurrent_sessions);
    extract(root, "vram_reserve_mb", config.vram_reserve_mb);
    extract_path(root, "config_dir", config.config_dir);
    extract_path(root, "log_dir", config.log_dir);
    extract(root, "ggml_logging", config.ggml_logging);
    extract_path(root, "llama_log_path", config.llama_log_path);  // gh#23 v2.3.24
    extract(root, "console_logging", config.console_logging);
 
    extract_tri_state_path(root, "constitution",
                           config.constitution, config.constitution_disabled);
    /* gh#141 (v2.11.0): app_context accepts an object carrying the text
     * inline, for consumers that hold it in memory and cannot write it to
     * disk. Checked BEFORE the tri-state path parse, because the object form
     * has no meaning as a path and would otherwise be stringified into one. */
    if (!extract_inline_content(root, "app_context",
                                config.app_context_content)) {
        extract_tri_state_path(root, "app_context",
                               config.app_context, config.app_context_disabled);
    }
    // gh#179 (v2.14.0): per-workspace app_context file, opt-in.
    extract_path(root, "workspace_app_context", config.workspace_app_context);
}
 
static std::string validate_workspace_app_context(const ParsedConfig& config) {
    const auto& p = config.workspace_app_context;
    std::string err;
    bool escapes = false;
    for (const auto& part : p) { escapes = escapes || part == ".."; }
    if (!p.empty() && (p.is_absolute() || escapes)) {
        err = "workspace_app_context must be a path relative to the workspace "
              "root with no '..' (got '" + p.string() + "')";
    }
    return err;
}
 
static std::string parse_optional_sections(
    ryml::ConstNodeRef root,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto err = parse_optional_subsections(root, registry, config);
    extract_scalar_fields(root, config);
    if (err.empty()) { err = validate_workspace_app_context(config); }  // gh#179
    if (err.empty() && root.has_child("delegation")) {
        err = parse_delegation_config(root["delegation"],
                                      config.delegation);
    }
    return err;
}
 
static std::string parse_top_sections(
    ryml::ConstNodeRef root,
    const BundledModels& registry,
    ParsedConfig& config)
{
    std::string err;
    if (root.has_child("models")) {
        err = parse_models_config(root["models"], registry, config.models);
    }
    if (err.empty() && root.has_child("routing")) {
        err = parse_routing_config(root["routing"], config.routing);
    }
    if (err.empty()) {
        err = parse_optional_sections(root, registry, config);
    }
    return err;
}
 
std::string parse_config_file(
    const std::filesystem::path& path,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto content = read_file(path);
    if (content.empty()) {
        return "cannot read config file: " + path.string();
    }
 
    ryml::Tree tree = ryml::parse_in_arena(
        ryml::to_csubstr(path.string()),
        ryml::to_csubstr(content));
    ryml::ConstNodeRef root = tree.rootref();
    if (!root.is_map()) {
        return "config file root is not a YAML mapping: " + path.string();
    }
 
    return parse_top_sections(root, registry, config);
}
 
static std::string load_bundled_default(
    const std::filesystem::path& global_path,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto data_dir = resolve_data_dir(config);
    auto bundled = data_dir / "default_config.yaml";
    if (!std::filesystem::exists(bundled)) {
        s_log->warn("No config found (checked global, project, bundled)");
        return "";
    }
    s_log->info("No user config — loading bundled default: {}",
                bundled.string());
    auto err = parse_config_file(bundled, registry, config);
    if (!err.empty()) { return "bundled default: " + err; }
 
    // Auto-create global config so this only happens once. gh#109
    // follow-up: load_layered() intentionally passes an empty global_path
    // (it doesn't want the auto-create side effect) — exists("") is
    // always false, so without this guard every fresh-install call
    // through load_layered (no ~/.entropic/config.yaml yet) threw
    // filesystem_error trying to create_directories("").
    if (!global_path.empty() && !std::filesystem::exists(global_path)) {
        auto parent = global_path.parent_path();
        std::filesystem::create_directories(parent);
        std::filesystem::copy_file(bundled, global_path);
        s_log->info("Created {}", global_path.string());
    }
    return "";
}
 
static std::string load_config_layers(
    const std::filesystem::path& global_path,
    const std::filesystem::path& project_path,
    const BundledModels& registry,
    ParsedConfig& config)
{
    bool have_config = false;
    std::string err;
 
    if (std::filesystem::exists(global_path)) {
        s_log->info("Loading global config: {}", global_path.string());
        err = parse_config_file(global_path, registry, config);
        if (!err.empty()) { return "global config: " + err; }
        have_config = true;
    }
 
    if (err.empty() && std::filesystem::exists(project_path)) {
        s_log->info("Loading project config: {}", project_path.string());
        err = parse_config_file(project_path, registry, config);
        if (!err.empty()) { return "project config: " + err; }
        have_config = true;
    }
 
    return have_config ? ""
        : load_bundled_default(global_path, registry, config);
}
 
std::string load_config(
    const std::filesystem::path& global_path,
    const std::filesystem::path& project_path,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto err = load_config_layers(global_path, project_path, registry, config);
    if (!err.empty()) { return err; }
 
    apply_env_overrides(config);
 
    std::vector<std::string> warnings;
    err = validate_config(config, warnings);
    for (const auto& w : warnings) { s_log->warn("{}", w); }
    return err;
}
 
std::string load_config_from_file(
    const std::filesystem::path& path,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto err = parse_config_file(path, registry, config);
    if (!err.empty()) {
        return err;
    }
 
    apply_env_overrides(config);
 
    std::vector<std::string> warnings;
    err = validate_config(config, warnings);
    for (const auto& w : warnings) {
        s_log->warn("{}", w);
    }
    return err;
}
 
static std::string load_global_layer(
    const BundledModels& registry, ParsedConfig& config)
{
    const char* home = getenv("HOME");
    std::string err;
    if (home) {
        auto path = std::filesystem::path(home) / ".entropic" / "config.yaml";
        if (std::filesystem::exists(path)) {
            s_log->info("Loading global config: {}", path.string());
            err = parse_config_file(path, registry, config);
            if (!err.empty()) {
                err = "global config: " + err;
            }
        }
    }
    return err;
}
 
static std::filesystem::path resolve_consumer_defaults(
    const std::filesystem::path& consumer_defaults)
{
    // Input already usable (empty, absolute, or found at CWD) → passthrough.
    if (consumer_defaults.empty()
        || consumer_defaults.is_absolute()
        || std::filesystem::exists(consumer_defaults)) {
        return consumer_defaults;
    }
    // Fall back to <install-prefix>/share/entropic/<filename>. Uses
    // the same librentropic.so location trick — dladdr on any address
    // in this translation unit resolves to the .so's on-disk path.
    std::filesystem::path result = consumer_defaults;
    Dl_info info = {};
    if (dladdr(reinterpret_cast<void*>(&resolve_consumer_defaults), &info) != 0
        && info.dli_fname != nullptr) {
        std::error_code ec;
        auto lib_path = std::filesystem::absolute(info.dli_fname, ec);
        if (!ec) {
            auto candidate = lib_path.parent_path().parent_path()
                / "share" / "entropic" / consumer_defaults.filename();
            if (std::filesystem::exists(candidate)) {
                result = candidate;
            }
        }
    }
    return result;
}
 
static bool yaml_has_key(const std::filesystem::path& path,
                         const char* key) {
    auto content = read_file(path);
    if (content.empty()) { return false; }
    auto tree = ryml::parse_in_arena(
        ryml::to_csubstr(path.string()),
        ryml::to_csubstr(content));
    auto root = tree.rootref();
    return root.is_map() && root.has_child(ryml::to_csubstr(key));
}
 
static void load_consumer_layer(
    const std::filesystem::path& consumer_defaults_in,
    const BundledModels& registry, ParsedConfig& config)
{
    auto consumer_defaults = resolve_consumer_defaults(consumer_defaults_in);
    if (consumer_defaults.empty() || !std::filesystem::exists(consumer_defaults)) {
        return;
    }
    s_log->info("Loading consumer defaults: {}", consumer_defaults.string());
 
    // Replace semantics: if consumer defines models or routing,
    // clear existing tiers/routing so global ones don't leak through.
    if (yaml_has_key(consumer_defaults, "models")) {
        s_log->info("Consumer defines models: — replacing global tiers");
        config.models.tiers.clear();
        config.models.router.reset();
        config.models.default_tier.clear();
    }
    if (yaml_has_key(consumer_defaults, "routing")) {
        config.routing = RoutingConfig{};
    }
 
    auto err = parse_config_file(consumer_defaults, registry, config);
    if (!err.empty()) {
        s_log->warn("Consumer defaults failed: {}", err);
    }
}
 
static std::string load_project_layer(
    const std::filesystem::path& project_dir,
    const BundledModels& registry, ParsedConfig& config)
{
    std::string err;
    if (!project_dir.empty()) {
        auto path = project_dir / "config.local.yaml";
        if (std::filesystem::exists(path)) {
            s_log->info("Loading project config: {}", path.string());
            if (yaml_has_key(path, "models")) {
                s_log->info("Project defines models: — replacing prior tiers");
                config.models.tiers.clear();
                config.models.router.reset();
                config.models.default_tier.clear();
            }
            if (yaml_has_key(path, "routing")) {
                config.routing = RoutingConfig{};
            }
            err = parse_config_file(path, registry, config);
            if (!err.empty()) {
                err = "project config: " + err;
            }
        }
    }
    return err;
}
 
std::string load_layered(
    const std::filesystem::path& project_dir,
    const std::filesystem::path& consumer_defaults,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto err = load_global_layer(registry, config);
    if (err.empty()) {
        load_consumer_layer(consumer_defaults, registry, config);
        if (!project_dir.empty() && config.log_dir.empty()) {
            config.log_dir = project_dir;
        }
        err = load_project_layer(project_dir, registry, config);
    }
    if (err.empty() && config.models.tiers.empty()) {
        // v2.11.1: parse into a SCRATCH config and transplant only the model
        // block. Previously this re-parsed the whole bundled default straight
        // over `config`, AFTER the project layer had already run — so a
        // fresh-install machine silently lost every setting an explicit layer
        // had established. data/default_config.yaml sets `mcp.enable_bash:
        // true`, so a project asking for false got true back, and REQ-CFG-001's
        // most-specific-layer-wins rule was violated by the layer that is
        // supposed to be LEAST specific.
        //
        // Invisible on any machine whose ~/.entropic/config.yaml declares tiers
        // (the fallback never fires there) and hit on every CI runner and every
        // fresh install. The condition that triggers it is a MISSING MODEL SET,
        // so the model set is the only thing it may supply.
        ParsedConfig fallback;
        fallback.config_dir = config.config_dir;
        err = load_bundled_default(std::filesystem::path{}, registry, fallback);
        if (err.empty()) {
            config.models = std::move(fallback.models);
        }
    }
    if (err.empty()) {
        // v2.14.0: .mcp.json is no longer merged here. This path only ever
        // fed `external_servers`, which nothing connected; discovery now runs
        // once, in the MCP layer, behind the enablement gate (gh#199).
        apply_env_overrides(config);
    }
    return err;
}
 
static std::string parse_config_string(
    const std::string& content,
    const BundledModels& registry,
    ParsedConfig& config)
{
    if (content.empty()) {
        return "config string is empty";
    }
 
    ryml::Tree tree = ryml::parse_in_arena(
        ryml::to_csubstr("<json>"),
        ryml::to_csubstr(content));
    auto root = tree.rootref();
    if (!root.is_map()) {
        return "config string root is not a mapping";
    }
 
    std::string err;
    if (root.has_child("models")) {
        err = parse_models_config(root["models"], registry, config.models);
    }
    if (err.empty() && root.has_child("routing")) {
        err = parse_routing_config(root["routing"], config.routing);
    }
    if (err.empty()) {
        err = parse_optional_sections(root, registry, config);
    }
    return err;
}
 
std::string load_config_from_string(
    const std::string& content,
    const BundledModels& registry,
    ParsedConfig& config)
{
    auto err = parse_config_string(content, registry, config);
    if (!err.empty()) {
        return err;
    }
 
    apply_env_overrides(config);
 
    std::vector<std::string> warnings;
    err = validate_config(config, warnings);
    for (const auto& w : warnings) {
        s_log->warn("{}", w);
    }
    return err;
}
 
} // namespace entropic::config