openkind-server 0.2.0

//! Daemon configuration and registration for surveyed-family engines.
//!
//! Each family exposes `--<family>-aliases` plus the artifact paths its
//! loader requires. An alias is only served when it appears in `--models`;
//! requesting a family alias without its artifact configuration fails the
//! daemon startup instead of falling back to the mock engine.

use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

use crate::args::{
    CudaOnlyBackendArg, DecoderLogitQwen35BackendArg, EncoderInstructLabelBackendArg,
    FamilyBackendArg, LayaBackendArg,
};
use anyhow::{bail, Context, Result};
use clap::Parser;
use openkind_backends::families::decider::{DeciderEngine, DeciderEngineConfig, DECIDER_4B};
use openkind_backends::families::decoder_logit_letter::{
    DecoderLetterEngine, DecoderLetterEngineConfig,
};
use openkind_backends::families::decoder_logit_llm::{DecoderLlmEngine, DecoderLlmEngineConfig};
use openkind_backends::families::decoder_logit_qwen3::{
    DecoderLogitQwen3Engine, DecoderLogitQwen3EngineConfig, QWEN3_06B, QWEN3_17B, QWEN3_4B,
};
use openkind_backends::families::decoder_logit_qwen35::{
    DecoderLogitQwen35Engine, DecoderLogitQwen35EngineConfig, PLUMB_4B,
};
use openkind_backends::families::gemma4::{Gemma4DecisionEngine, Gemma4EngineConfig};

#[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
use openkind_backends::families::decoder_logit_qwen35::{
    DecoderLogitQwen35MlxEngine, DecoderLogitQwen35MlxEngineConfig,
};
use openkind_backends::families::encoder_instruct_label::{
    EncoderInstructLabelEngine, EncoderInstructLabelEngineConfig,
};

#[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
use openkind_backends::families::encoder_instruct_label::{
    EncoderInstructLabelMlxEngine, EncoderInstructLabelMlxEngineConfig,
};
use openkind_backends::families::encoder_nli::{EncoderNliEngine, EncoderNliEngineConfig};
use openkind_backends::families::kev::{KevEngine, KevEngineConfig};
use openkind_backends::families::laya::{
    LayaEngine, LayaEngineConfig, LAYA_ENGLISH, LAYA_MULTILINGUAL, LAYA_TYPED_DECISIONS,
};
#[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
use openkind_backends::families::laya::{LayaMlxEngine, LayaMlxEngineConfig};
use openkind_backends::families::qwen3guard::{Qwen3GuardEngine, Qwen3GuardEngineConfig};
use openkind_backends::families::router_script::ScriptRuleTable;
use openkind_backends::families::schema_scorer::{SchemaScorerEngine, SchemaScorerEngineConfig};
use openkind_backends::families::strands_decider::{
    StrandsDeciderEngine, StrandsDeciderEngineConfig,
};
use openkind_backends::families::support::FamilyLimits;
use openkind_backends::families::von::{VonEngine, VonEngineConfig, VON};
use openkind_engine::DecisionEngine;

/// Admission defaults shared by all surveyed-family engines.
#[derive(Debug, Clone, Copy)]
pub(crate) struct FamilyAdmission {
    pub(crate) concurrency: usize,
    pub(crate) queue: usize,
    pub(crate) timeout_ms: u64,
}

impl FamilyAdmission {
    fn limits(self) -> FamilyLimits {
        FamilyLimits {
            max_concurrent_requests: self.concurrency,
            max_queued_requests: self.queue,
            retry_after_ms: 1_000,
            evaluation_timeout: Some(Duration::from_millis(self.timeout_ms)),
        }
    }
}

/// Surveyed-family daemon configuration.
#[derive(Debug, Parser, Clone)]
pub(crate) struct FamilyArgs {
    /// Aliases in `--models` that should use the pinned decoder-logit-letter
    /// engine (Qwen2.5-0.5B-Instruct letter readout).
    #[arg(
        long,
        env = "OPENKIND_DECODER_LETTER_ALIASES",
        value_delimiter = ',',
        default_value = "decoder-letter-native"
    )]
    pub(crate) decoder_letter_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`, and
    /// `tokenizer.json` required by decoder-letter aliases.
    #[arg(long, env = "OPENKIND_DECODER_LETTER_MODEL_ROOT")]
    pub(crate) decoder_letter_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned encoder-nli engine
    /// (DistilBERT MNLI entailment readout).
    #[arg(
        long,
        env = "OPENKIND_ENCODER_NLI_ALIASES",
        value_delimiter = ',',
        default_value = "encoder-nli-native"
    )]
    pub(crate) encoder_nli_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`, and
    /// `vocab.txt` required by encoder-nli aliases.
    #[arg(long, env = "OPENKIND_ENCODER_NLI_MODEL_ROOT")]
    pub(crate) encoder_nli_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned
    /// encoder-instruct-label engine (GLiClass label-marker readout).
    #[arg(
        long,
        env = "OPENKIND_ENCODER_INSTRUCT_LABEL_ALIASES",
        value_delimiter = ',',
        default_value = "encoder-instruct-label-native"
    )]
    pub(crate) encoder_instruct_label_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`, and
    /// `tokenizer.json` required by encoder-instruct-label aliases.
    #[arg(long, env = "OPENKIND_ENCODER_INSTRUCT_LABEL_MODEL_ROOT")]
    pub(crate) encoder_instruct_label_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned kev engine
    /// (Kev-0.6B pointer readout on Qwen3-0.6B-Base).
    #[arg(
        long,
        env = "OPENKIND_KEV_ALIASES",
        value_delimiter = ',',
        default_value = "kev-native"
    )]
    pub(crate) kev_aliases: Vec<String>,

    /// Model root with the pinned kev checkpoint artifacts
    /// (`adapter_model.safetensors`, `tokenizer.json`, `head.safetensors`).
    #[arg(long, env = "OPENKIND_KEV_MODEL_ROOT")]
    pub(crate) kev_model_root: Option<PathBuf>,

    /// Base-model root with the pinned `Qwen3-0.6B-Base`
    /// (`model.safetensors`, `config.json`).
    #[arg(long, env = "OPENKIND_KEV_BASE_ROOT")]
    pub(crate) kev_base_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned strands-decider-2b
    /// engine (Strands Decider 2B pointer readout on Qwen3.5-2B-Base).
    #[arg(
        long,
        env = "OPENKIND_STRANDS_DECIDER_ALIASES",
        value_delimiter = ',',
        default_value = "strands-decider-native"
    )]
    pub(crate) strands_decider_aliases: Vec<String>,

    /// Model root with the pinned Strands Decider 2B checkpoint artifacts
    /// (`adapter_model.safetensors`, `adapter_config.json`,
    /// `head.safetensors`, `tokenizer.json`, `hobson_config.json`).
    #[arg(long, env = "OPENKIND_STRANDS_DECIDER_MODEL_ROOT")]
    pub(crate) strands_decider_model_root: Option<PathBuf>,

    /// Base-model root with the pinned `Qwen3.5-2B-Base`
    /// (`model.safetensors`, `config.json`).
    #[arg(long, env = "OPENKIND_STRANDS_DECIDER_BASE_ROOT")]
    pub(crate) strands_decider_base_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned decoder-logit-llm
    /// engine (GGUF q8_0 letter readout).
    #[arg(
        long,
        env = "OPENKIND_DECODER_LLM_ALIASES",
        value_delimiter = ',',
        default_value = "decoder-llm-native"
    )]
    pub(crate) decoder_llm_aliases: Vec<String>,

    /// Model root with the pinned `qwen2.5-0.5b-instruct-q8_0.gguf` and
    /// `tokenizer.json` required by decoder-llm aliases.
    #[arg(long, env = "OPENKIND_DECODER_LLM_MODEL_ROOT")]
    pub(crate) decoder_llm_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned schema-scorer engine
    /// (MS MARCO cross-encoder scalar readout).
    #[arg(
        long,
        env = "OPENKIND_SCHEMA_SCORER_ALIASES",
        value_delimiter = ',',
        default_value = "schema-scorer-native"
    )]
    pub(crate) schema_scorer_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`, and
    /// `tokenizer.json` required by schema-scorer aliases.
    #[arg(long, env = "OPENKIND_SCHEMA_SCORER_MODEL_ROOT")]
    pub(crate) schema_scorer_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the router-script composite.
    #[arg(
        long,
        env = "OPENKIND_ROUTER_SCRIPT_ALIASES",
        value_delimiter = ',',
        default_value = "router-script"
    )]
    pub(crate) router_script_aliases: Vec<String>,

    /// Rule table for router-script aliases: comma-separated
    /// `script=alias` pairs plus a `default=alias` route. Sibling aliases
    /// must also be served through `--models`.
    #[arg(
        long,
        env = "OPENKIND_ROUTER_SCRIPT_RULES",
        value_delimiter = ';',
        default_value = "latin=decoder-letter-native,cyrillic=encoder-nli-native,default=decoder-letter-native"
    )]
    pub(crate) router_script_rules: Vec<String>,

    /// Aliases in `--models` that should use the pinned qwen3guard engine
    /// (Qwen3Guard-Stream risk-level readout).
    #[arg(
        long,
        env = "OPENKIND_QWEN3GUARD_ALIASES",
        value_delimiter = ',',
        default_value = "qwen3guard-native"
    )]
    pub(crate) qwen3guard_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`, and
    /// `tokenizer.json` required by qwen3guard aliases.
    #[arg(long, env = "OPENKIND_QWEN3GUARD_MODEL_ROOT")]
    pub(crate) qwen3guard_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned von engine
    /// (von-1.1 option-marker readout).
    #[arg(
        long,
        env = "OPENKIND_VON_ALIASES",
        value_delimiter = ',',
        default_value = "von-native"
    )]
    pub(crate) von_aliases: Vec<String>,

    /// Model root with the pinned `checkpoint/` directory required by von
    /// aliases.
    #[arg(long, env = "OPENKIND_VON_MODEL_ROOT")]
    pub(crate) von_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the winnow learned router.
    #[arg(
        long,
        env = "OPENKIND_WINNOW_ALIASES",
        value_delimiter = ',',
        default_value = "winnow-router"
    )]
    pub(crate) winnow_aliases: Vec<String>,

    /// Model root with the pinned base checkpoint and tokenizer required by
    /// winnow aliases.
    #[arg(long, env = "OPENKIND_WINNOW_MODEL_ROOT")]
    pub(crate) winnow_model_root: Option<PathBuf>,

    /// Path to the pinned winnow LoRA adapter.
    #[arg(long, env = "OPENKIND_WINNOW_ADAPTER")]
    pub(crate) winnow_adapter: Option<PathBuf>,

    /// Routing labels for winnow aliases: `A=<sibling alias>,B=<sibling
    /// alias>`. Sibling aliases must also be served through `--models`.
    #[arg(
        long,
        env = "OPENKIND_WINNOW_SIBLINGS",
        value_delimiter = ';',
        default_value = "A=decoder-letter-native,B=encoder-nli-native"
    )]
    pub(crate) winnow_siblings: Vec<String>,

    /// Aliases in `--models` that should use the pinned
    /// decoder-logit-qwen35 engine (JevK5 letter-logit readout on the
    /// Qwen3.5 hybrid backbone).
    #[arg(
        long,
        env = "OPENKIND_DECODER_LOGIT_QWEN35_ALIASES",
        value_delimiter = ',',
        default_value = "jevk5-native"
    )]
    pub(crate) decoder_logit_qwen35_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`,
    /// `jevk5_config.json`, and `tokenizer.json` required by
    /// decoder-logit-qwen35 aliases.
    #[arg(long, env = "OPENKIND_DECODER_LOGIT_QWEN35_MODEL_ROOT")]
    pub(crate) decoder_logit_qwen35_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned plumb-4b engine
    /// (Plumb-4B letter-logit readout on the Qwen3.5 hybrid backbone).
    #[arg(
        long,
        env = "OPENKIND_PLUMB_4B_ALIASES",
        value_delimiter = ',',
        default_value = "plumb-4b-native"
    )]
    pub(crate) plumb_4b_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`,
    /// `jevk5_config.json`, and `tokenizer.json` required by plumb-4b
    /// aliases.
    #[arg(long, env = "OPENKIND_PLUMB_4B_MODEL_ROOT")]
    pub(crate) plumb_4b_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned decider-4b engine
    /// (slot-logit readout on the Qwen3.5 hybrid backbone).
    #[arg(
        long,
        env = "OPENKIND_DECIDER_4B_ALIASES",
        value_delimiter = ',',
        default_value = "decider-4b-native"
    )]
    pub(crate) decider_4b_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `config.json`,
    /// `decider_config.json`, and `tokenizer.json` required by decider-4b
    /// aliases.
    #[arg(long, env = "OPENKIND_DECIDER_4B_MODEL_ROOT")]
    pub(crate) decider_4b_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned raw decoder-logit-
    /// qwen3 controls (letter-logit readout on the dense Qwen3 checkpoints).
    #[arg(
        long,
        env = "OPENKIND_DECODER_LOGIT_QWEN3_ALIASES",
        value_delimiter = ';',
        help = "semicolon-separated alias lists of the form 06b=<alias>[,alias…];17b=<alias>[,alias…];4b=<alias>[,alias…]"
    )]
    pub(crate) decoder_logit_qwen3_aliases: Vec<String>,

    /// Model roots for the raw decoder-logit-qwen3 controls, of the form
    /// `06b=<path>;17b=<path>;4b=<path>`.
    #[arg(
        long,
        env = "OPENKIND_DECODER_LOGIT_QWEN3_MODEL_ROOTS",
        value_delimiter = ';',
        help = "semicolon-separated model roots of the form 06b=<path>;17b=<path>;4b=<path>"
    )]
    pub(crate) decoder_logit_qwen3_model_roots: Vec<String>,

    /// Aliases in `--models` that should use a pinned Cloudflare Clef
    /// engine, of the form `flash=<alias>[,alias…];flash-gguf=<…>;27b=<…>`.
    #[arg(
        long,
        env = "OPENKIND_CLEF_ALIASES",
        value_delimiter = ';',
        help = "semicolon-separated alias lists of the form flash=<alias>[,alias…];flash-gguf=<alias>[,alias…];27b=<alias>[,alias…]"
    )]
    pub(crate) clef_aliases: Vec<String>,

    /// Model roots for the pinned Cloudflare Clef profiles, of the form
    /// `flash=<path>;flash-gguf=<path>;27b=<path>`.
    #[arg(
        long,
        env = "OPENKIND_CLEF_MODEL_ROOTS",
        value_delimiter = ';',
        help = "semicolon-separated model roots of the form flash=<path>;flash-gguf=<path>;27b=<path>"
    )]
    pub(crate) clef_model_roots: Vec<String>,

    /// Aliases in `--models` that should use the pinned laya-english engine
    /// (English ModernBERT-large decision encoder).
    #[arg(
        long,
        env = "OPENKIND_LAYA_ENGLISH_ALIASES",
        value_delimiter = ',',
        default_value = "laya-english-native"
    )]
    pub(crate) laya_english_aliases: Vec<String>,

    /// Model root with the pinned `model.safetensors`, `encoder/`,
    /// `tokenizer/`, and `rl_agent_config.json` required by laya-english
    /// aliases.
    #[arg(long, env = "OPENKIND_LAYA_ENGLISH_MODEL_ROOT")]
    pub(crate) laya_english_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned laya-multilingual
    /// engine (mmBERT-base decision encoder, 100+ languages).
    #[arg(
        long,
        env = "OPENKIND_LAYA_MULTILINGUAL_ALIASES",
        value_delimiter = ',',
        default_value = "laya-multilingual-native"
    )]
    pub(crate) laya_multilingual_aliases: Vec<String>,

    /// Model root with the pinned multilingual laya artifacts.
    #[arg(long, env = "OPENKIND_LAYA_MULTILINGUAL_MODEL_ROOT")]
    pub(crate) laya_multilingual_model_root: Option<PathBuf>,

    /// Aliases in `--models` that should use the pinned
    /// laya-typed-decisions engine (fine-tuned ModernBERT-large).
    #[arg(
        long,
        env = "OPENKIND_LAYA_TYPED_DECISIONS_ALIASES",
        value_delimiter = ',',
        default_value = "laya-typed-decisions-native"
    )]
    pub(crate) laya_typed_decisions_aliases: Vec<String>,

    /// Model root with the pinned typed-decisions laya artifacts.
    #[arg(long, env = "OPENKIND_LAYA_TYPED_DECISIONS_MODEL_ROOT")]
    pub(crate) laya_typed_decisions_model_root: Option<PathBuf>,

    /// Laya decision-encoder backend. `cuda` requires the daemon's `cuda`
    /// feature; `onnx`/`onnx-cuda` require the ONNX features and `model.onnx`
    /// in the model root; `mlx-fp32` is available on macOS arm64 with the
    /// daemon's `mlx` feature enabled.
    #[arg(
        long,
        env = "OPENKIND_LAYA_BACKEND",
        value_enum,
        default_value_t = LayaBackendArg::Auto
    )]
    pub(crate) laya_backend: LayaBackendArg,

    /// Encoder-instruct-label backend. `cuda` requires the daemon's `cuda`
    /// feature; `onnx`/`onnx-cuda` require the ONNX features and `model.onnx`
    /// in the model root; `mlx-fp32` is available on macOS arm64 with the
    /// daemon's `mlx` feature enabled.
    #[arg(
        long,
        env = "OPENKIND_ENCODER_INSTRUCT_LABEL_BACKEND",
        value_enum,
        default_value_t = EncoderInstructLabelBackendArg::Auto
    )]
    pub(crate) encoder_instruct_label_backend: EncoderInstructLabelBackendArg,

    /// decoder-logit-qwen35 backend. `cuda` requires the daemon's `cuda`
    /// feature; `mlx-fp32` is available on macOS arm64 with the daemon's
    /// `mlx` feature enabled.
    #[arg(
        long,
        env = "OPENKIND_DECODER_LOGIT_QWEN35_BACKEND",
        value_enum,
        default_value_t = DecoderLogitQwen35BackendArg::Auto
    )]
    pub(crate) decoder_logit_qwen35_backend: DecoderLogitQwen35BackendArg,

    /// Encoder-NLI backend. `cuda` requires the daemon's `cuda` feature;
    /// `onnx`/`onnx-cuda` require the ONNX features and `model.onnx` in the
    /// model root.
    #[arg(
        long,
        env = "OPENKIND_ENCODER_NLI_BACKEND",
        value_enum,
        default_value_t = FamilyBackendArg::Auto
    )]
    pub(crate) encoder_nli_backend: FamilyBackendArg,

    /// Decoder-logit-letter backend. `cuda` requires the daemon's `cuda`
    /// feature; `onnx`/`onnx-cuda` require the ONNX features and `model.onnx`
    /// in the model root.
    #[arg(
        long,
        env = "OPENKIND_DECODER_LETTER_BACKEND",
        value_enum,
        default_value_t = FamilyBackendArg::Auto
    )]
    pub(crate) decoder_letter_backend: FamilyBackendArg,

    /// Kev backend. The pointer-head readout has no ONNX export; `cuda`
    /// requires the daemon's `cuda` feature.
    #[arg(
        long,
        env = "OPENKIND_KEV_BACKEND",
        value_enum,
        default_value_t = CudaOnlyBackendArg::Auto
    )]
    pub(crate) kev_backend: CudaOnlyBackendArg,

    /// Strands-decider-2b backend. The pointer-head readout over the
    /// Qwen3.5 hybrid backbone has no ONNX export; `cuda` requires the
    /// daemon's `cuda` feature.
    #[arg(
        long,
        env = "OPENKIND_STRANDS_DECIDER_BACKEND",
        value_enum,
        default_value_t = CudaOnlyBackendArg::Auto
    )]
    pub(crate) strands_decider_backend: CudaOnlyBackendArg,

    /// Decoder-logit-llm backend. The quantized GGUF readout has no ONNX
    /// export; `cuda` requires the daemon's `cuda` feature.
    #[arg(
        long,
        env = "OPENKIND_DECODER_LLM_BACKEND",
        value_enum,
        default_value_t = CudaOnlyBackendArg::Auto
    )]
    pub(crate) decoder_llm_backend: CudaOnlyBackendArg,

    /// Schema-scorer backend. `cuda` requires the daemon's `cuda` feature;
    /// `onnx`/`onnx-cuda` require the ONNX features and `model.onnx` in the
    /// model root.
    #[arg(
        long,
        env = "OPENKIND_SCHEMA_SCORER_BACKEND",
        value_enum,
        default_value_t = FamilyBackendArg::Auto
    )]
    pub(crate) schema_scorer_backend: FamilyBackendArg,

    /// Qwen3Guard backend. `cuda` requires the daemon's `cuda` feature;
    /// `onnx`/`onnx-cuda` require the ONNX features and `model.onnx` in the
    /// model root.
    #[arg(
        long,
        env = "OPENKIND_QWEN3GUARD_BACKEND",
        value_enum,
        default_value_t = FamilyBackendArg::Auto
    )]
    pub(crate) qwen3guard_backend: FamilyBackendArg,

    /// Von backend. `cuda` requires the daemon's `cuda` feature;
    /// `onnx`/`onnx-cuda` require the ONNX features and `model.onnx` in the
    /// model root.
    #[arg(
        long,
        env = "OPENKIND_VON_BACKEND",
        value_enum,
        default_value_t = FamilyBackendArg::Auto
    )]
    pub(crate) von_backend: FamilyBackendArg,

    /// Raw decoder-logit-qwen3 controls backend (applies to every size).
    /// `cuda` requires the daemon's `cuda` feature; `onnx`/`onnx-cuda`
    /// require the ONNX features and `model.onnx` in each model root.
    #[arg(
        long,
        env = "OPENKIND_DECODER_LOGIT_QWEN3_BACKEND",
        value_enum,
        default_value_t = FamilyBackendArg::Auto
    )]
    pub(crate) decoder_logit_qwen3_backend: FamilyBackendArg,

    /// Decider-4b backend. The hybrid-backbone slot-logit readout has no
    /// ONNX export; `cuda` requires the daemon's `cuda` feature.
    #[arg(
        long,
        env = "OPENKIND_DECIDER_4B_BACKEND",
        value_enum,
        default_value_t = CudaOnlyBackendArg::Auto
    )]
    pub(crate) decider_4b_backend: CudaOnlyBackendArg,

    /// Aliases in `--models` that should use the pinned winnow-e4b engine
    /// (Gemma 4 backbone letter readout on the Winnow-E4B Q8_0 GGUF).
    #[arg(
        long,
        env = "OPENKIND_WINNOW_E4B_ALIASES",
        value_delimiter = ',',
        default_value = "winnow-e4b-native"
    )]
    pub(crate) winnow_e4b_aliases: Vec<String>,

    /// Model root with the pinned `Winnow-E4B-Q8_0.gguf` and
    /// `tokenizer.json` required by winnow-e4b aliases.
    #[arg(long, env = "OPENKIND_WINNOW_E4B_MODEL_ROOT")]
    pub(crate) winnow_e4b_model_root: Option<PathBuf>,

    /// Winnow-e4b backend. The Gemma 4 backbone has no ONNX export; `cuda`
    /// requires the daemon's `cuda` feature.
    #[arg(
        long,
        env = "OPENKIND_WINNOW_E4B_BACKEND",
        value_enum,
        default_value_t = CudaOnlyBackendArg::Auto
    )]
    pub(crate) winnow_e4b_backend: CudaOnlyBackendArg,

    /// Winnow router backend. The routing decoder has no ONNX export;
    /// `cuda` requires the daemon's `cuda` feature.
    #[arg(
        long,
        env = "OPENKIND_WINNOW_BACKEND",
        value_enum,
        default_value_t = CudaOnlyBackendArg::Auto
    )]
    pub(crate) winnow_backend: CudaOnlyBackendArg,

    /// Maximum concurrent model evaluations per surveyed-family engine.
    #[arg(long, env = "OPENKIND_FAMILY_CONCURRENCY", default_value_t = 1)]
    pub(crate) family_concurrency: usize,

    /// Additional family requests allowed to wait for execution.
    #[arg(long, env = "OPENKIND_FAMILY_QUEUE", default_value_t = 2)]
    pub(crate) family_queue: usize,

    /// Queue-inclusive deadline for one family evaluation, in milliseconds.
    #[arg(long, env = "OPENKIND_FAMILY_TIMEOUT_MS", default_value_t = 600_000)]
    pub(crate) family_timeout_ms: u64,
}

fn parse_qwen3_size(size: &str) -> Result<&'static str> {
    match size {
        "06b" => Ok("06b"),
        "17b" => Ok("17b"),
        "4b" => Ok("4b"),
        other => {
            bail!("unknown decoder-logit-qwen3 control size `{other}`; expected 06b, 17b, or 4b")
        }
    }
}

fn parse_clef_size(size: &str) -> Result<&'static str> {
    match size {
        "flash" => Ok("flash"),
        "flash-gguf" => Ok("flash-gguf"),
        "27b" => Ok("27b"),
        other => {
            bail!("unknown clef profile key `{other}`; expected flash, flash-gguf, or 27b")
        }
    }
}

impl FamilyArgs {
    pub(crate) fn parse_decoder_logit_qwen3_aliases(&self) -> Result<Vec<(&'static str, String)>> {
        let mut result = Vec::new();
        let mut seen_aliases = HashMap::new();
        for raw_entry in &self.decoder_logit_qwen3_aliases {
            for entry in raw_entry.split(';') {
                let entry = entry.trim();
                if entry.is_empty() {
                    continue;
                }
                let Some((size_raw, alias_names)) = entry.split_once('=') else {
                    bail!(
                        "--decoder-logit-qwen3-aliases entries must look like 06b=<alias>[,alias…]; got {entry}"
                    );
                };
                let size = parse_qwen3_size(size_raw.trim())?;
                for alias_name in alias_names.split(',') {
                    let alias_name = alias_name.trim();
                    if alias_name.is_empty() {
                        bail!(
                            "--decoder-logit-qwen3-aliases entries must look like 06b=<alias>[,alias…]; got empty alias name in {entry}"
                        );
                    }
                    if let Some(existing_size) = seen_aliases.get(alias_name) {
                        if *existing_size != size {
                            bail!(
                                "alias `{alias_name}` is assigned to more than one decoder-logit-qwen3 control size (`{existing_size}` and `{size}`)"
                            );
                        } else {
                            bail!(
                                "duplicate alias `{alias_name}` in --decoder-logit-qwen3-aliases"
                            );
                        }
                    }
                    seen_aliases.insert(alias_name.to_string(), size);
                    result.push((size, alias_name.to_string()));
                }
            }
        }
        Ok(result)
    }

    pub(crate) fn parse_decoder_logit_qwen3_model_roots(
        &self,
    ) -> Result<BTreeMap<&'static str, PathBuf>> {
        let mut roots = BTreeMap::new();
        for raw_entry in &self.decoder_logit_qwen3_model_roots {
            for entry in raw_entry.split(';') {
                let entry = entry.trim();
                if entry.is_empty() {
                    continue;
                }
                let Some((size_raw, root_raw)) = entry.split_once('=') else {
                    bail!(
                        "--decoder-logit-qwen3-model-roots entries must look like 06b=<path>; got {entry}"
                    );
                };
                let size = parse_qwen3_size(size_raw.trim())?;
                let root = root_raw.trim();
                if root.is_empty() {
                    bail!(
                        "--decoder-logit-qwen3-model-roots has empty path for size `{size}` in {entry}"
                    );
                }
                if roots.contains_key(size) {
                    bail!("duplicate decoder-logit-qwen3 model root for size `{size}`");
                }
                roots.insert(size, PathBuf::from(root));
            }
        }
        Ok(roots)
    }

    pub(crate) fn parse_clef_aliases(&self) -> Result<Vec<(&'static str, String)>> {
        let mut result = Vec::new();
        let mut seen_aliases = HashMap::new();
        for raw_entry in &self.clef_aliases {
            for entry in raw_entry.split(';') {
                let entry = entry.trim();
                if entry.is_empty() {
                    continue;
                }
                let Some((size_raw, alias_names)) = entry.split_once('=') else {
                    bail!(
                        "--clef-aliases entries must look like flash=<alias>[,alias…]; got {entry}"
                    );
                };
                let size = parse_clef_size(size_raw.trim())?;
                for alias_name in alias_names.split(',') {
                    let alias_name = alias_name.trim();
                    if alias_name.is_empty() {
                        bail!(
                            "--clef-aliases entries must look like flash=<alias>[,alias…]; got empty alias name in {entry}"
                        );
                    }
                    if let Some(existing_size) = seen_aliases.get(alias_name) {
                        if *existing_size != size {
                            bail!(
                                "alias `{alias_name}` is assigned to more than one clef profile key (`{existing_size}` and `{size}`)"
                            );
                        } else {
                            bail!("duplicate alias `{alias_name}` in --clef-aliases");
                        }
                    }
                    seen_aliases.insert(alias_name.to_string(), size);
                    result.push((size, alias_name.to_string()));
                }
            }
        }
        Ok(result)
    }

    pub(crate) fn parse_clef_model_roots(&self) -> Result<BTreeMap<&'static str, PathBuf>> {
        let mut roots = BTreeMap::new();
        for raw_entry in &self.clef_model_roots {
            for entry in raw_entry.split(';') {
                let entry = entry.trim();
                if entry.is_empty() {
                    continue;
                }
                let Some((size_raw, root_raw)) = entry.split_once('=') else {
                    bail!("--clef-model-roots entries must look like flash=<path>; got {entry}");
                };
                let size = parse_clef_size(size_raw.trim())?;
                let root = root_raw.trim();
                if root.is_empty() {
                    bail!("--clef-model-roots has empty path for size `{size}` in {entry}");
                }
                if roots.contains_key(size) {
                    bail!("duplicate clef model root for key `{size}`");
                }
                roots.insert(size, PathBuf::from(root));
            }
        }
        Ok(roots)
    }

    /// Return the set of all family aliases configured in CLI flags or environment variables.
    pub(crate) fn claimed_aliases(&self) -> Result<BTreeSet<String>> {
        let mut claimed = BTreeSet::new();
        for alias in self
            .decoder_letter_aliases
            .iter()
            .chain(&self.encoder_nli_aliases)
            .chain(&self.encoder_instruct_label_aliases)
            .chain(&self.decoder_llm_aliases)
            .chain(&self.schema_scorer_aliases)
            .chain(&self.router_script_aliases)
            .chain(&self.qwen3guard_aliases)
            .chain(&self.von_aliases)
            .chain(&self.winnow_aliases)
            .chain(&self.winnow_e4b_aliases)
            .chain(&self.kev_aliases)
            .chain(&self.strands_decider_aliases)
            .chain(&self.decoder_logit_qwen35_aliases)
            .chain(&self.plumb_4b_aliases)
            .chain(&self.decider_4b_aliases)
            .chain(&self.laya_english_aliases)
            .chain(&self.laya_multilingual_aliases)
            .chain(&self.laya_typed_decisions_aliases)
        {
            claimed.insert(alias.clone());
        }
        for (_, alias) in self.parse_decoder_logit_qwen3_aliases()? {
            claimed.insert(alias);
        }
        for (_, alias) in self.parse_clef_aliases()? {
            claimed.insert(alias);
        }
        Ok(claimed)
    }

    fn admission(&self) -> FamilyAdmission {
        FamilyAdmission {
            concurrency: self.family_concurrency,
            queue: self.family_queue,
            timeout_ms: self.family_timeout_ms,
        }
    }

    /// Load every family engine whose aliases intersect `--models`.
    ///
    /// Returns `(alias, engine)` pairs ready for `EngineRegistry`
    /// registration. Missing artifact configuration fails closed.
    pub(crate) fn load_requested(
        &self,
        models: &[String],
        devices: crate::args::DeviceOrdinals,
    ) -> Result<Vec<(String, Arc<dyn DecisionEngine>)>> {
        let admission = self.admission();
        let mut engines = Vec::new();

        let decoder_letter: Vec<_> = self
            .decoder_letter_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !decoder_letter.is_empty() {
            let model_root = self.decoder_letter_model_root.clone().context(
                "decoder-letter alias requested but --decoder-letter-model-root is missing",
            )?;
            let engine: Arc<dyn DecisionEngine> = crate::backend::load(
                self.decoder_letter_backend,
                &model_root,
                devices,
                |backend| {
                    Ok(Arc::new(
                        DecoderLetterEngine::load_with_execution(
                            DecoderLetterEngineConfig {
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load decoder-logit-letter engine")?,
                    ) as Arc<dyn DecisionEngine>)
                },
            )?;
            for alias in decoder_letter {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let encoder_nli: Vec<_> = self
            .encoder_nli_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !encoder_nli.is_empty() {
            let model_root = self
                .encoder_nli_model_root
                .clone()
                .context("encoder-nli alias requested but --encoder-nli-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.encoder_nli_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        EncoderNliEngine::load_with_execution(
                            EncoderNliEngineConfig {
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load encoder-nli engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in encoder_nli {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let encoder_instruct_label: Vec<_> = self
            .encoder_instruct_label_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !encoder_instruct_label.is_empty() {
            let model_root = self
                .encoder_instruct_label_model_root
                .clone()
                .context(
                    "encoder-instruct-label alias requested but                      --encoder-instruct-label-model-root is missing",
                )?;
            let engine: Arc<dyn DecisionEngine> = crate::backend::load(
                self.encoder_instruct_label_backend,
                &model_root,
                devices,
                |backend| {
                    Ok(match backend {
                        EncoderInstructLabelBackendArg::Auto => {
                            unreachable!("auto resolves before loading")
                        }
                        EncoderInstructLabelBackendArg::NativeCpu => Arc::new(
                            EncoderInstructLabelEngine::load_with_execution(
                                EncoderInstructLabelEngineConfig {
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::NativeCpu.to_execution(devices)?,
                            )
                            .context("load encoder-instruct-label engine")?,
                        ),
                        #[cfg(feature = "cuda")]
                        EncoderInstructLabelBackendArg::Cuda => Arc::new(
                            EncoderInstructLabelEngine::load_with_execution(
                                EncoderInstructLabelEngineConfig {
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::Cuda.to_execution(devices)?,
                            )
                            .context("load encoder-instruct-label engine")?,
                        ),
                        #[cfg(feature = "onnx")]
                        EncoderInstructLabelBackendArg::Onnx => Arc::new(
                            EncoderInstructLabelEngine::load_with_execution(
                                EncoderInstructLabelEngineConfig {
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::Onnx.to_execution(devices)?,
                            )
                            .context("load encoder-instruct-label engine")?,
                        ),
                        #[cfg(feature = "onnx")]
                        EncoderInstructLabelBackendArg::OnnxCuda => Arc::new(
                            EncoderInstructLabelEngine::load_with_execution(
                                EncoderInstructLabelEngineConfig {
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::OnnxCuda.to_execution(devices)?,
                            )
                            .context("load encoder-instruct-label engine")?,
                        ),
                        #[cfg(feature = "onnx")]
                        EncoderInstructLabelBackendArg::OnnxRocm => Arc::new(
                            EncoderInstructLabelEngine::load_with_execution(
                                EncoderInstructLabelEngineConfig {
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::OnnxRocm.to_execution(devices)?,
                            )
                            .context("load encoder-instruct-label engine")?,
                        ),
                        #[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
                        EncoderInstructLabelBackendArg::MlxFp32 => Arc::new(
                            EncoderInstructLabelMlxEngine::load(
                                EncoderInstructLabelMlxEngineConfig {
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                            )
                            .context("load encoder-instruct-label mlx engine")?,
                        ),
                    } as Arc<dyn DecisionEngine>)
                },
            )?;
            for alias in encoder_instruct_label {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let decoder_llm: Vec<_> = self
            .decoder_llm_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !decoder_llm.is_empty() {
            let model_root = self
                .decoder_llm_model_root
                .clone()
                .context("decoder-llm alias requested but --decoder-llm-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.decoder_llm_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        DecoderLlmEngine::load_with_execution(
                            DecoderLlmEngineConfig {
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load decoder-logit-llm engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in decoder_llm {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let kev: Vec<_> = self
            .kev_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !kev.is_empty() {
            let model_root = self
                .kev_model_root
                .clone()
                .context("kev alias requested but --kev-model-root is missing")?;
            let base_root = self
                .kev_base_root
                .clone()
                .context("kev alias requested but --kev-base-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.kev_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        KevEngine::load_with_execution(
                            KevEngineConfig {
                                model_root: model_root.clone(),
                                base_root: base_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load kev engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in kev {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let strands_decider: Vec<_> = self
            .strands_decider_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !strands_decider.is_empty() {
            let model_root = self.strands_decider_model_root.clone().context(
                "strands-decider alias requested but --strands-decider-model-root is missing",
            )?;
            let base_root = self.strands_decider_base_root.clone().context(
                "strands-decider alias requested but --strands-decider-base-root is missing",
            )?;
            let engine: Arc<dyn DecisionEngine> = crate::backend::load(
                self.strands_decider_backend,
                &model_root,
                devices,
                |backend| {
                    Ok(Arc::new(
                        StrandsDeciderEngine::load_with_execution(
                            StrandsDeciderEngineConfig {
                                model_root: model_root.clone(),
                                base_root: base_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load strands-decider-2b engine")?,
                    ) as Arc<dyn DecisionEngine>)
                },
            )?;
            for alias in strands_decider {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let schema_scorer: Vec<_> = self
            .schema_scorer_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !schema_scorer.is_empty() {
            let model_root = self.schema_scorer_model_root.clone().context(
                "schema-scorer alias requested but --schema-scorer-model-root is missing",
            )?;
            let engine: Arc<dyn DecisionEngine> = crate::backend::load(
                self.schema_scorer_backend,
                &model_root,
                devices,
                |backend| {
                    Ok(Arc::new(
                        SchemaScorerEngine::load_with_execution(
                            SchemaScorerEngineConfig {
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load schema-scorer engine")?,
                    ) as Arc<dyn DecisionEngine>)
                },
            )?;
            for alias in schema_scorer {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let qwen3guard: Vec<_> = self
            .qwen3guard_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !qwen3guard.is_empty() {
            let model_root = self
                .qwen3guard_model_root
                .clone()
                .context("qwen3guard alias requested but --qwen3guard-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.qwen3guard_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        Qwen3GuardEngine::load_with_execution(
                            Qwen3GuardEngineConfig {
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load qwen3guard engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in qwen3guard {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let von: Vec<_> = self
            .von_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !von.is_empty() {
            let model_root = self
                .von_model_root
                .clone()
                .context("von alias requested but --von-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.von_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        VonEngine::load_with_execution(
                            VonEngineConfig {
                                profile: &VON,
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load von engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in von {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let decoder_logit_qwen35: Vec<_> = self
            .decoder_logit_qwen35_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !decoder_logit_qwen35.is_empty() {
            let model_root = self
                .decoder_logit_qwen35_model_root
                .clone()
                .context(
                    "decoder-logit-qwen35 alias requested but                      --decoder-logit-qwen35-model-root is missing",
                )?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(
                    self.decoder_logit_qwen35_backend,
                    &model_root,
                    devices,
                    |backend| {
                        Ok(match backend {
                DecoderLogitQwen35BackendArg::Auto => unreachable!("auto resolves before loading"),
                DecoderLogitQwen35BackendArg::NativeCpu => Arc::new(
                    DecoderLogitQwen35Engine::load(DecoderLogitQwen35EngineConfig {
                        profile: &openkind_backends::families::decoder_logit_qwen35::JEVK5,
                        model_root: model_root.clone(),
                        limits: admission.limits(),
                    })
                    .context("load decoder-logit-qwen35 engine")?,
                ),
                #[cfg(feature = "cuda")]
                DecoderLogitQwen35BackendArg::Cuda => Arc::new(
                    DecoderLogitQwen35Engine::load_with_execution(
                        DecoderLogitQwen35EngineConfig {
                            profile: &openkind_backends::families::decoder_logit_qwen35::JEVK5,
                            model_root: model_root.clone(),
                            limits: admission.limits(),
                        },
                        FamilyBackendArg::Cuda.to_execution(devices)?,
                    )
                    .context("load decoder-logit-qwen35 engine")?,
                ),
                #[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
                DecoderLogitQwen35BackendArg::MlxFp32 => Arc::new(
                    DecoderLogitQwen35MlxEngine::load(DecoderLogitQwen35MlxEngineConfig {
                        profile: &openkind_backends::families::decoder_logit_qwen35::JEVK5,
                        model_root: model_root.clone(),
                        limits: admission.limits(),
                    })
                    .context("load decoder-logit-qwen35 mlx engine")?,
                ),
            } as Arc<dyn DecisionEngine>)
                    },
                )?;
            for alias in decoder_logit_qwen35 {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let plumb_4b: Vec<_> = self
            .plumb_4b_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !plumb_4b.is_empty() {
            let model_root = self
                .plumb_4b_model_root
                .clone()
                .context("plumb-4b alias requested but --plumb-4b-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> = crate::backend::load(
                self.decoder_logit_qwen35_backend,
                &model_root,
                devices,
                |backend| {
                    Ok(match backend {
                        DecoderLogitQwen35BackendArg::Auto => {
                            unreachable!("auto resolves before loading")
                        }
                        DecoderLogitQwen35BackendArg::NativeCpu => Arc::new(
                            DecoderLogitQwen35Engine::load(DecoderLogitQwen35EngineConfig {
                                profile: &PLUMB_4B,
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            })
                            .context("load plumb-4b engine")?,
                        ),
                        #[cfg(feature = "cuda")]
                        DecoderLogitQwen35BackendArg::Cuda => Arc::new(
                            DecoderLogitQwen35Engine::load_with_execution(
                                DecoderLogitQwen35EngineConfig {
                                    profile: &PLUMB_4B,
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::Cuda.to_execution(devices)?,
                            )
                            .context("load plumb-4b engine")?,
                        ),
                        #[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
                        DecoderLogitQwen35BackendArg::MlxFp32 => Arc::new(
                            DecoderLogitQwen35MlxEngine::load(DecoderLogitQwen35MlxEngineConfig {
                                profile: &PLUMB_4B,
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            })
                            .context("load plumb-4b mlx engine")?,
                        ),
                    } as Arc<dyn DecisionEngine>)
                },
            )?;
            for alias in plumb_4b {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        // Raw decoder-logit-qwen3 controls: size-keyed alias lists and model
        // roots (`06b=`, `17b=`, `4b=` prefixes).
        let qwen3_aliases = self.parse_decoder_logit_qwen3_aliases()?;
        let qwen3_roots = self.parse_decoder_logit_qwen3_model_roots()?;
        let mut qwen3_requested: Vec<(String, &'static str)> = Vec::new();
        for (size, alias) in qwen3_aliases {
            if models.contains(&alias) {
                qwen3_requested.push((alias, size));
            }
        }
        if !qwen3_requested.is_empty() {
            let mut loaded_engines: HashMap<&'static str, Arc<dyn DecisionEngine>> = HashMap::new();
            for (alias, size) in qwen3_requested {
                let model_root = qwen3_roots.get(size).ok_or_else(|| {
                    anyhow::anyhow!(
                        "decoder-logit-qwen3-{size} alias `{alias}` requested but --decoder-logit-qwen3-model-roots has no root for {size}"
                    )
                })?;
                let profile = match size {
                    "06b" => &QWEN3_06B,
                    "17b" => &QWEN3_17B,
                    "4b" => &QWEN3_4B,
                    other => unreachable!("validated size {other}"),
                };
                let engine = if let Some(existing) = loaded_engines.get(size) {
                    Arc::clone(existing)
                } else {
                    let engine: Arc<dyn DecisionEngine> = crate::backend::load(
                        self.decoder_logit_qwen3_backend,
                        model_root,
                        devices,
                        |backend| {
                            Ok(Arc::new(
                                DecoderLogitQwen3Engine::load_with_execution(
                                    DecoderLogitQwen3EngineConfig {
                                        profile,
                                        model_root: model_root.clone(),
                                        limits: admission.limits(),
                                    },
                                    backend.to_execution(devices)?,
                                )
                                .with_context(|| {
                                    format!("load decoder-logit-qwen3-{size} engine")
                                })?,
                            ) as Arc<dyn DecisionEngine>)
                        },
                    )?;
                    loaded_engines.insert(size, Arc::clone(&engine));
                    engine
                };
                engines.push((alias, engine));
            }
        }

        // Cloudflare Clef joint-schema profiles: size-keyed alias lists and
        // model roots (`flash=`, `flash-gguf=`, `27b=` prefixes). Every
        // profile executes on the candle CPU path.
        let clef_aliases = self.parse_clef_aliases()?;
        let clef_roots = self.parse_clef_model_roots()?;
        let mut clef_requested: Vec<(String, &'static str)> = Vec::new();
        for (size, alias) in clef_aliases {
            if models.contains(&alias) {
                clef_requested.push((alias, size));
            }
        }
        if !clef_requested.is_empty() {
            let mut loaded_engines: HashMap<&'static str, Arc<dyn DecisionEngine>> = HashMap::new();
            for (alias, size) in clef_requested {
                let model_root = clef_roots.get(size).ok_or_else(|| {
                    anyhow::anyhow!(
                        "clef-{size} alias `{alias}` requested but --clef-model-roots has no root for {size}"
                    )
                })?;
                let profile = match size {
                    "flash" => &openkind_backends::families::clef::CLEF_FLASH,
                    "flash-gguf" => &openkind_backends::families::clef::CLEF_FLASH_GGUF,
                    "27b" => &openkind_backends::families::clef::CLEF_27B_GGUF,
                    other => unreachable!("validated size {other}"),
                };
                let engine = if let Some(existing) = loaded_engines.get(size) {
                    Arc::clone(existing)
                } else {
                    let engine: Arc<dyn DecisionEngine> = Arc::new(
                        openkind_backends::families::clef::ClefEngine::load(
                            model_root.clone(),
                            profile,
                            admission.limits(),
                        )
                        .with_context(|| format!("load clef-{size} engine"))?,
                    );
                    loaded_engines.insert(size, Arc::clone(&engine));
                    engine
                };
                engines.push((alias, engine));
            }
        }

        let decider_4b: Vec<_> = self
            .decider_4b_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !decider_4b.is_empty() {
            let model_root = self
                .decider_4b_model_root
                .clone()
                .context("decider-4b alias requested but --decider-4b-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.decider_4b_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        DeciderEngine::load_with_execution(
                            DeciderEngineConfig {
                                profile: &DECIDER_4B,
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load decider-4b engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in decider_4b {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let winnow_e4b: Vec<_> = self
            .winnow_e4b_aliases
            .iter()
            .filter(|alias| models.contains(alias))
            .collect();
        if !winnow_e4b.is_empty() {
            let model_root = self
                .winnow_e4b_model_root
                .clone()
                .context("winnow-e4b alias requested but --winnow-e4b-model-root is missing")?;
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.winnow_e4b_backend, &model_root, devices, |backend| {
                    Ok(Arc::new(
                        Gemma4DecisionEngine::load_with_execution(
                            Gemma4EngineConfig {
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            },
                            backend.to_execution(devices)?,
                        )
                        .context("load winnow-e4b engine")?,
                    ) as Arc<dyn DecisionEngine>)
                })?;
            for alias in winnow_e4b {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        let mut laya_requested: Vec<(
            Vec<&String>,
            PathBuf,
            &openkind_backends::families::laya::LayaProfile,
            &str,
        )> = Vec::new();
        for (aliases, model_root, profile, name) in [
            (
                &self.laya_english_aliases,
                self.laya_english_model_root.clone(),
                &LAYA_ENGLISH,
                "laya-english",
            ),
            (
                &self.laya_multilingual_aliases,
                self.laya_multilingual_model_root.clone(),
                &LAYA_MULTILINGUAL,
                "laya-multilingual",
            ),
            (
                &self.laya_typed_decisions_aliases,
                self.laya_typed_decisions_model_root.clone(),
                &LAYA_TYPED_DECISIONS,
                "laya-typed-decisions",
            ),
        ] {
            let requested: Vec<_> = aliases
                .iter()
                .filter(|alias| models.contains(alias))
                .collect();
            if requested.is_empty() {
                continue;
            }
            let model_root = model_root.context(format!(
                "{name} alias requested but --{name}-model-root is missing"
            ))?;
            laya_requested.push((requested, model_root, profile, name));
        }
        for (requested, model_root, profile, name) in laya_requested {
            let engine: Arc<dyn DecisionEngine> =
                crate::backend::load(self.laya_backend, &model_root, devices, |backend| {
                    Ok(match backend {
                        LayaBackendArg::Auto => unreachable!("auto resolves before loading"),
                        LayaBackendArg::NativeCpu => Arc::new(
                            LayaEngine::load_with_execution(
                                LayaEngineConfig {
                                    profile,
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::NativeCpu.to_execution(devices)?,
                            )
                            .with_context(|| format!("load {name} engine"))?,
                        ),
                        #[cfg(feature = "cuda")]
                        LayaBackendArg::Cuda => Arc::new(
                            LayaEngine::load_with_execution(
                                LayaEngineConfig {
                                    profile,
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::Cuda.to_execution(devices)?,
                            )
                            .with_context(|| format!("load {name} engine"))?,
                        ),
                        #[cfg(feature = "onnx")]
                        LayaBackendArg::Onnx => Arc::new(
                            LayaEngine::load_with_execution(
                                LayaEngineConfig {
                                    profile,
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::Onnx.to_execution(devices)?,
                            )
                            .with_context(|| format!("load {name} engine"))?,
                        ),
                        #[cfg(feature = "onnx")]
                        LayaBackendArg::OnnxCuda => Arc::new(
                            LayaEngine::load_with_execution(
                                LayaEngineConfig {
                                    profile,
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::OnnxCuda.to_execution(devices)?,
                            )
                            .with_context(|| format!("load {name} engine"))?,
                        ),
                        #[cfg(feature = "onnx")]
                        LayaBackendArg::OnnxRocm => Arc::new(
                            LayaEngine::load_with_execution(
                                LayaEngineConfig {
                                    profile,
                                    model_root: model_root.clone(),
                                    limits: admission.limits(),
                                },
                                FamilyBackendArg::OnnxRocm.to_execution(devices)?,
                            )
                            .with_context(|| format!("load {name} engine"))?,
                        ),
                        #[cfg(all(feature = "mlx", target_os = "macos", target_arch = "aarch64"))]
                        LayaBackendArg::MlxFp32 => Arc::new(
                            LayaMlxEngine::load(LayaMlxEngineConfig {
                                profile,
                                model_root: model_root.clone(),
                                limits: admission.limits(),
                            })
                            .with_context(|| format!("load {name} mlx engine"))?,
                        ),
                    } as Arc<dyn DecisionEngine>)
                })?;
            for alias in requested {
                engines.push((alias.to_string(), Arc::clone(&engine)));
            }
        }

        Ok(engines)
    }

    /// Winnow aliases requested through `--models`, with their sibling
    /// label bindings. Routing composition happens after the sibling
    /// engines are registered, so this returns configuration only.
    pub(crate) fn winnow_requested(&self, models: &[String]) -> Result<Vec<(String, Vec<String>)>> {
        let mut requested = Vec::new();
        for (alias, siblings) in self.winnow_aliases.iter().zip(
            self.winnow_siblings
                .iter()
                .chain(std::iter::repeat(&self.winnow_siblings[0])),
        ) {
            if !models.contains(alias) {
                continue;
            }
            let mut labels: Vec<String> = Vec::new();
            let mut bindings = std::collections::BTreeMap::new();
            for token in siblings.split(',') {
                let (label, sibling) = token.split_once('=').ok_or_else(|| {
                    anyhow::anyhow!("expected `A=alias` in --winnow-siblings, found `{token}`")
                })?;
                let label = label.trim();
                match label {
                    "A" | "B" => {}
                    other => anyhow::bail!("unknown winnow label `{other}`"),
                }
                let sibling = sibling.trim();
                if sibling.is_empty() {
                    anyhow::bail!("winnow label `{label}` requires a non-empty sibling alias");
                }
                if bindings.insert(label, sibling).is_some() {
                    anyhow::bail!("duplicate winnow label `{label}`");
                }
            }
            if bindings.len() != 2 {
                anyhow::bail!("--winnow-siblings needs exactly two labels A and B");
            }
            // Learned logits are ordered A, B regardless of flag token order.
            for label in ["A", "B"] {
                labels.push(bindings[label].to_owned());
            }
            requested.push((alias.clone(), labels));
        }
        Ok(requested)
    }

    /// Artifact configuration for winnow aliases.
    pub(crate) fn winnow_artifacts(&self, alias: &str) -> Result<(PathBuf, PathBuf)> {
        let model_root = self
            .winnow_model_root
            .clone()
            .context("winnow alias requested but --winnow-model-root is missing")?;
        let adapter = self
            .winnow_adapter
            .clone()
            .context("winnow alias requested but --winnow-adapter is missing")?;
        let _ = alias;
        Ok((model_root, adapter))
    }

    /// Router-script aliases requested through `--models`, with their rule
    /// tables. Routing composition happens after the sibling engines are
    /// registered, so this returns configuration only.
    pub(crate) fn router_script_requested(
        &self,
        models: &[String],
    ) -> Result<Vec<(String, ScriptRuleTable)>> {
        let mut requested = Vec::new();
        for (alias, rules) in self.router_script_aliases.iter().zip(
            self.router_script_rules
                .iter()
                .chain(std::iter::repeat(&self.router_script_rules[0])),
        ) {
            if models.contains(alias) {
                let table = ScriptRuleTable::parse(rules)
                    .context("parse --router-script-rules for `{alias}`")?;
                requested.push((alias.clone(), table));
            }
        }
        Ok(requested)
    }

    /// Reject duplicate native or family aliases that would shadow each other.
    pub(crate) fn validate(&self, native_aliases: &[String]) -> Result<()> {
        let mut seen = std::collections::BTreeSet::new();
        for alias in self
            .decoder_letter_aliases
            .iter()
            .chain(&self.encoder_nli_aliases)
            .chain(&self.encoder_instruct_label_aliases)
            .chain(&self.decoder_llm_aliases)
            .chain(&self.schema_scorer_aliases)
            .chain(&self.router_script_aliases)
            .chain(&self.qwen3guard_aliases)
            .chain(&self.von_aliases)
            .chain(&self.winnow_aliases)
            .chain(&self.winnow_e4b_aliases)
            .chain(&self.kev_aliases)
            .chain(&self.strands_decider_aliases)
            .chain(&self.decoder_logit_qwen35_aliases)
            .chain(&self.plumb_4b_aliases)
            .chain(&self.decider_4b_aliases)
            .chain(&self.laya_english_aliases)
            .chain(&self.laya_multilingual_aliases)
            .chain(&self.laya_typed_decisions_aliases)
        {
            if !seen.insert(alias.as_str()) {
                bail!("alias `{alias}` is assigned to more than one family engine");
            }
        }

        let qwen3_aliases = self.parse_decoder_logit_qwen3_aliases()?;
        for (_, alias) in &qwen3_aliases {
            if !seen.insert(alias.as_str()) {
                bail!("alias `{alias}` is assigned to more than one family engine");
            }
        }
        self.parse_decoder_logit_qwen3_model_roots()?;

        let clef_aliases = self.parse_clef_aliases()?;
        for (_, alias) in &clef_aliases {
            if !seen.insert(alias.as_str()) {
                bail!("alias `{alias}` is assigned to more than one family engine");
            }
        }
        self.parse_clef_model_roots()?;

        for alias in native_aliases {
            if !seen.insert(alias.as_str()) {
                bail!("alias `{alias}` is assigned to more than one family engine");
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn winnow_label_bindings_follow_labels_instead_of_input_order() {
        let args = FamilyArgs::parse_from(["openkindd", "--winnow-siblings", "B=second,A=first"]);
        assert_eq!(
            args.winnow_requested(&["winnow-router".into()]).unwrap(),
            vec![(
                "winnow-router".into(),
                vec!["first".into(), "second".into()]
            )]
        );
    }

    #[test]
    fn winnow_rejects_duplicate_missing_and_empty_label_bindings() {
        for bindings in [
            "A=first,A=second",
            "B=first,B=second",
            "A=first",
            "A=,B=second",
        ] {
            let args = FamilyArgs::parse_from(["openkindd", "--winnow-siblings", bindings]);
            assert!(
                args.winnow_requested(&["winnow-router".into()]).is_err(),
                "{bindings}"
            );
        }
    }

    #[test]
    fn native_aliases_cannot_shadow_family_aliases() {
        let args = FamilyArgs::parse_from(["openkindd"]);
        assert!(args.validate(&["qwen35-native".into()]).is_ok());
        assert!(args.validate(&["decoder-letter-native".into()]).is_err());
        assert!(args.validate(&["router-script".into()]).is_err());
    }
}

#[cfg(test)]
mod fail_closed_tests {
    use super::*;
    use crate::args::DeviceOrdinals;

    /// Requesting a family alias without its `--*-model-root` (or the
    /// clef/decoder-logit-qwen3 per-profile roots) must fail closed before
    /// any artifact is touched.
    #[test]
    fn missing_model_roots_fail_closed_per_family() {
        for (alias, needle) in [
            (
                "decoder-letter-native",
                "--decoder-letter-model-root is missing",
            ),
            ("encoder-nli-native", "--encoder-nli-model-root is missing"),
        ] {
            let args = FamilyArgs::parse_from(["openkindd"]);
            let error = match args.load_requested(&[alias.to_owned()], DeviceOrdinals::default()) {
                Err(error) => format!("{error:#}"),
                Ok(engines) => panic!(
                    "{alias}: expected failure, loaded {} engine(s)",
                    engines.len()
                ),
            };
            assert!(
                error.contains(needle),
                "{alias}: expected `{needle}` in: {error}"
            );
        }
    }

    #[test]
    fn decoder_logit_qwen3_root_entries_must_carry_sizes_and_known_keys() {
        let args =
            FamilyArgs::parse_from(["openkindd", "--decoder-logit-qwen3-model-roots", "badentry"]);
        let error = match args.load_requested(
            &["decoder-logit-qwen3-06b-native".to_owned()],
            DeviceOrdinals::default(),
        ) {
            Err(error) => format!("{error:#}"),
            Ok(engines) => panic!("expected failure, loaded {} engine(s)", engines.len()),
        };
        // A malformed entry fails even before the alias/root lookup.
        assert!(
            error.contains("badentry") || error.contains("model-root is missing"),
            "{error}"
        );

        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-model-roots",
            "99b=/tmp/nowhere",
        ]);
        let error = match args.load_requested(
            &["decoder-logit-qwen3-06b-native".to_owned()],
            DeviceOrdinals::default(),
        ) {
            Err(error) => format!("{error:#}"),
            Ok(engines) => panic!("unknown size must fail, loaded {} engine(s)", engines.len()),
        };
        assert!(
            error.contains("99b") && error.contains("expected 06b"),
            "{error}"
        );

        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-aliases",
            "06b=decoder-logit-qwen3-06b-native",
            "--decoder-logit-qwen3-model-roots",
            "06b=/tmp/nowhere",
        ]);
        let error = match args.load_requested(
            &["decoder-logit-qwen3-06b-native".to_owned()],
            DeviceOrdinals::default(),
        ) {
            Err(error) => format!("{error:#}"),
            Ok(engines) => panic!("missing root must fail, loaded {} engine(s)", engines.len()),
        };
        assert!(error.contains("06b"), "{error}");
    }

    #[test]
    fn missing_qwen3_root_fails_closed() {
        let args =
            FamilyArgs::parse_from(["openkindd", "--decoder-logit-qwen3-aliases", "17b=victim17"]);
        let error = match args.load_requested(&["victim17".to_owned()], DeviceOrdinals::default()) {
            Err(error) => format!("{error:#}"),
            Ok(engines) => panic!("expected failure, loaded {} engine(s)", engines.len()),
        };
        assert!(
            error.contains("decoder-logit-qwen3-17b") && error.contains("no root for 17b"),
            "{error}"
        );
    }

    #[test]
    fn documented_qwen3_multiprofile_syntax_parses_and_attempts_load() {
        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-aliases",
            "06b=victim06;17b=victim17;4b=victim4",
            "--decoder-logit-qwen3-model-roots",
            "06b=/nonexistent/06;17b=/nonexistent/17;4b=/nonexistent/4",
        ]);
        let error = match args.load_requested(&["victim17".to_owned()], DeviceOrdinals::default()) {
            Err(error) => format!("{error:#}"),
            Ok(engines) => panic!("expected failure, loaded {} engine(s)", engines.len()),
        };
        assert!(
            error.contains("load decoder-logit-qwen3-17b engine"),
            "{error}"
        );
    }

    #[test]
    fn qwen3_multiple_aliases_per_size_and_claimed() {
        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-aliases",
            "06b=alias1,alias2;17b=alias3",
        ]);
        let claimed = args.claimed_aliases().unwrap();
        assert!(claimed.contains("alias1"));
        assert!(claimed.contains("alias2"));
        assert!(claimed.contains("alias3"));
    }

    #[test]
    fn qwen3_duplicate_and_colliding_aliases_fail_validation() {
        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-aliases",
            "06b=dup;17b=dup",
        ]);
        assert!(args.validate(&[]).is_err());

        let args =
            FamilyArgs::parse_from(["openkindd", "--decoder-logit-qwen3-aliases", "06b=dup,dup"]);
        assert!(args.validate(&[]).is_err());

        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-aliases",
            "06b=qwen35-native",
        ]);
        assert!(args.validate(&["qwen35-native".into()]).is_err());

        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-aliases",
            "06b=decoder-letter-native",
        ]);
        assert!(args.validate(&[]).is_err());
    }

    #[test]
    fn qwen3_duplicate_model_roots_fail_closed() {
        let args = FamilyArgs::parse_from([
            "openkindd",
            "--decoder-logit-qwen3-model-roots",
            "06b=/path1;06b=/path2",
        ]);
        assert!(args.validate(&[]).is_err());
        assert!(args.load_requested(&[], DeviceOrdinals::default()).is_err());
    }

    #[test]
    fn missing_clef_root_fails_closed() {
        let args = FamilyArgs::parse_from(["openkindd", "--clef-aliases", "flash=clef-flash"]);
        let error = match args.load_requested(&["clef-flash".to_owned()], DeviceOrdinals::default())
        {
            Err(error) => format!("{error:#}"),
            Ok(engines) => panic!("expected failure, loaded {} engine(s)", engines.len()),
        };
        assert!(
            error.contains("clef-flash") && error.contains("no root for flash"),
            "{error}"
        );
    }
}