Skip to main content

Configuration Engine

Architectural Layer: L1 Configuration
Source Directory: src/config
File Count: 11 source files

8-tier hierarchical configuration precedence, strict schema validation, canonical defaults, and provenance.

Module Files & Detailed Reference​

Source FileLinesKey TypesResponsibility
canonical.rs241ModelCatalogCachePolicy, ResourcePolicy, TimeoutPolicySingle authoritative configuration defaults (CFG-01). This module is ...
env.rs78SafeEnvironmentStatusSecure environment configuration status (CFG-01, CFG-03). Production ...
hierarchy.rs126ConfigPrecedenceEngine, ConfigTier7-Tier Hierarchical Configuration Engine (CFG-01, D-12).
merge.rs245MonotonicSecurityMerger, ConfigErrorTOML Merging & Monotonic Security Accumulation (CFG-01, D-12, THRE...
mod.rs37Functions/TraitsHierarchical Configuration Engine & Validation (CFG-01–CFG-04, D-1...
paths.rs230PlatformPathsPlatform-Aware Configuration & Data Directories (CFG-03, D-14). C...
profile.rs265ProfileConfig, ProfileResolverComposable Configuration Profiles & Single Inheritance (CFG-04).
provenance.rs292ConfigurationService, LayerEntry, ResolvedValue7-Layer Configuration Provenance & Immutable Constraint Protection...
provider_registry.rs960MaskedSecret, ProviderDescriptor, ProviderProbeReportNVIDIA-NIM-Only Provider Registry & Masked Secret Boundaries (CFX-...
resolved.rs1345ConfigExplain, ResolvedConfigBuilder, ResolvedConfigurationUnified Authoritative Configuration Control Plane (CFG-01..04). Provi...
schema.rs1085AgentsConfig, AppConfig, CacheConfigStrict Configuration Schema & Validation (CFG-02, D-13).

src/config/canonical.rs​

Primary Responsibility​

Single authoritative configuration defaults (CFG-01). This module is the ONLY place where ordinary runtime defaults live. Every other subsystem consumes these values via the configuration resolver ([crate::config::ResolvedConfiguration]) — never by re-stating the literal. Split of responsibilities: - Configurable defaults → here (consumed by schema.rs default_* fns). - Immutable security floors / protocol constants → remain in code at their owning security layer (e.g. endpoint trust, egress policy, sandbox ceilings, query ceilings). - Serialization compatibility defaults → near the schema. Lower layers MUST NOT unwrap_or("<literal>") for any value listed here. They receive the resolved value from ResolvedConfiguration or fail closed.

Types & Trait Declarations​

  • Structs (3): ModelCatalogCachePolicy, ResourcePolicy, TimeoutPolicy

Key Functions & Signatures (4 shown)​

// pub
fn normalize_objective(input: Option<&str>) -> Option<String>;
// private
fn default() -> Self;
// private
fn default() -> Self;
// private
fn default() -> Self;

src/config/env.rs​

Primary Responsibility​

Secure environment configuration status (CFG-01, CFG-03). Production credential rule: production code under src/ MUST NOT discover LLM API keys through the process environment and MUST NOT load .env files. The single production credential authority is [crate::runtime_authorities::resolve_runtime_credentials] (canonical channel-isolated credential store → legacy workspace migration file, and nothing else). .env loading and LLM API-key environment reads for explicitly opted-in live-model testing live exclusively under tests/support/ (see tests/support/credentials.rs). They are never part of the production library. The only environment values consulted here are NON-SECRET, explicitly supported Tier-5 configuration overrides (model selection display only). Secrets (API keys, tokens) are NEVER logged or printed.

Types & Trait Declarations​

  • Structs (1): SafeEnvironmentStatus

Key Functions & Signatures (3 shown)​

// pub
fn probe() -> Self;
// pub
fn probe_workspace(workspace_root: &Path) -> Self;
// pub
fn log_status(&self);

src/config/hierarchy.rs​

Primary Responsibility​

7-Tier Hierarchical Configuration Engine (CFG-01, D-12).

Types & Trait Declarations​

  • Structs (1): ConfigPrecedenceEngine
  • Enums (1): ConfigTier

Key Functions & Signatures (9 shown)​

// pub
fn name(&self) -> &'static str;
// pub
fn new() -> Self;
// pub
fn set_layer(&mut self, tier: ConfigTier, value: toml::Value);
// pub
fn set_layer_from_str(&mut self,
        tier: ConfigTier,
        toml_str: &str,) -> Result<(), ConfigError>;
// pub
fn remove_layer(&mut self, tier: ConfigTier) -> Option<toml::Value>;
// pub
fn has_layer(&self, tier: ConfigTier) -> bool;
// pub
fn get_layer(&self, tier: ConfigTier) -> Option<&toml::Value>;
// pub
fn resolve_raw(&self) -> Result<toml::Value, ConfigError>;
// pub
fn resolve(&self) -> Result<T, ConfigError>;

src/config/merge.rs​

Primary Responsibility​

TOML Merging & Monotonic Security Accumulation (CFG-01, D-12, THREAT-05).

Types & Trait Declarations​

  • Structs (1): MonotonicSecurityMerger
  • Enums (1): ConfigError

Key Functions & Signatures (3 shown)​

// private
fn from(err: crate::config::schema::ConfigValidationError) -> Self;
// pub
fn deep_merge_toml(base: &mut toml::Value, overlay: toml::Value);
// pub
fn check(base: &toml::Value, overlay: &toml::Value) -> Result<(), ConfigError>;

src/config/mod.rs​

Primary Responsibility​

Hierarchical Configuration Engine & Validation (CFG-01–CFG-04, D-12–D-14).

src/config/paths.rs​

Primary Responsibility​

Platform-Aware Configuration & Data Directories (CFG-03, D-14). Compatibility layer over the canonical storage authority ([crate::storage::StorageLayout] / [crate::deployment::DeploymentPaths]). Global directory resolution delegates to DeploymentPaths; only legacy fallback file locations (.m31, /etc/m31) remain here as explicit migration boundaries.

Types & Trait Declarations​

  • Structs (1): PlatformPaths

Key Functions & Signatures (15 shown)​

// private
fn default() -> Self;
// pub
fn new() -> Self;
// pub
fn for_channel(channel: crate::deployment::DeploymentChannel) -> Self;
// pub
fn channel(&self) -> crate::deployment::DeploymentChannel;
// private
fn deployment_paths(&self) -> &crate::deployment::DeploymentPaths;
// pub
fn config_dir(&self) -> PathBuf;
// pub
fn data_dir(&self) -> PathBuf;
// pub
fn cache_dir(&self) -> PathBuf;
// pub
fn state_dir(&self) -> PathBuf;
// pub
fn system_config_dir(&self) -> PathBuf;
// pub
fn user_config_file(&self) -> PathBuf;
// pub
fn system_config_file(&self) -> PathBuf;
// pub
fn canonical_workspace_config_file(workspace_root: &Path) -> PathBuf;
// pub
fn workspace_config_candidates(workspace_root: &Path) -> Vec<PathBuf>;
// pub
fn workspace_config_file(workspace_root: &Path) -> PathBuf;

src/config/profile.rs​

Primary Responsibility​

Composable Configuration Profiles & Single Inheritance (CFG-04).

Types & Trait Declarations​

  • Structs (2): ProfileConfig, ProfileResolver

Key Functions & Signatures (15 shown)​

// private
fn default() -> Self;
// pub
fn new() -> Self;
// pub
fn with_canonical_profiles() -> Self;
// pub
fn register_profile(&mut self, name: &str, profile_toml: toml::Value);
// private
fn register_canonical_profiles(&mut self);
// pub
fn resolve_profile(&self, profile_name: &str) -> Result<toml::Value, ConfigError>;
// private
fn resolve_profile_recursive(&self,
        profile_name: &str,
        visited: &mut HashSet<String>,) -> Result<toml::;
// pub
fn apply_to_app_config(&self,
        profile_name: &str,
        mut base_config_toml: toml::Value,) -> Result<AppConfi;
// pub
fn canonical_profile_names() -> &'static [&'static str];
// pub
fn canonical_autonomy_for_profile(profile_name: &str) -> Result<String, ConfigError>;
// pub
fn canonical_metadata_for_profile(profile_name: &str) -> Result<toml::Value, ConfigError>;
// pub
fn is_canonical_profile(profile_name: &str) -> bool;
// private
fn normalize_profile_name(name: &str) -> String;
// private
fn hyphenated_profile_aliases_resolve_to_canonical_profiles();
// private
fn profile_names_are_normalized_when_registered_and_resolved();

Unit Verification (3 inline tests)​

Tests defined within module: hyphenated_profile_aliases_resolve_to_canonical_profiles, profile_names_are_normalized_when_registered_and_resolved, canonical_profile_inventory_excludes_aliases

src/config/provenance.rs​

Primary Responsibility​

7-Layer Configuration Provenance & Immutable Constraint Protection (CFX-04, D-07). Enforces the 7-tier precedence hierarchy (CLI > Session > Mission > Workspace > User > System > BuiltIn) and prevents lower-precedence configuration layers from weakening immutable safety constraints.

Types & Trait Declarations​

  • Structs (3): ConfigurationService, LayerEntry, ResolvedValue
  • Enums (2): ConfigLayer, ProvenanceError

Key Functions & Signatures (11 shown)​

// pub
fn precedence(&self) -> u8;
// pub
fn display_name(&self) -> &'static str;
// pub
fn badge(&self) -> &'static str;
// private
fn from(layer: ConfigLayer) -> Self;
// private
fn from(tier: ConfigTier) -> Self;
// pub
fn new() -> Self;
// pub
fn set_value(&mut self,
        layer: ConfigLayer,
        key: &str,
        value: serde_json::Value,
        source_;
// pub
fn resolve(&self, key: &str) -> Option<ResolvedValue>;
// pub
fn all_resolved(&self) -> Vec<ResolvedValue>;
// pub
fn grouped_by_domain(&self) -> BTreeMap<String, Vec<ResolvedValue>>;
// pub
fn get_all_entries_for_key(&self,
        key: &str,) -> Vec<(ConfigLayer, serde_json::Value, Option<PathBuf>, bool)>;

src/config/provider_registry.rs​

Primary Responsibility​

NVIDIA-NIM-Only Provider Registry & Masked Secret Boundaries (CFX-01, CFX-02, D-08). NVIDIA NIM is the sole production model provider in the current release. The registry retains retired provider descriptors (OpenAI, Anthropic, Gemini, OpenAI-Compatible/Local) exclusively so that ordinary configuration, /model selection, and environment resolution can reject them deterministically with a precise NVIDIA-only error. Retired entries are never exposed through production surfaces (production_descriptors, setup wizard, /model, model selector). Mock remains strictly as test infrastructure and is unreachable from normal user interaction.

Types & Trait Declarations​

  • Structs (4): MaskedSecret, ProviderDescriptor, ProviderProbeReport, ProviderRegistry
  • Enums (2): ProviderError, ProviderType

Key Functions & Signatures (15 shown)​

// pub
fn normalize_provider_id(id: &str) -> String;
// pub
fn is_production_provider_id(id: &str) -> bool;
// private
fn canonical_id_owned(id: &str) -> String;
// pub
fn is_retired_provider(id: &str) -> bool;
// pub
fn display_name(&self) -> &'static str;
// pub
fn is_production(&self) -> bool;
// pub
fn new(secret: impl Into<String>) -> Self;
// pub
fn is_empty(&self) -> bool;
// pub
fn expose_secret(&self) -> &str;
// pub
fn masked(&self) -> String;
// private
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result;
// private
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result;
// private
fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,;
// private
fn deserialize(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,;
// private
fn from(e: std::io::Error) -> Self;

Unit Verification (5 inline tests)​

Tests defined within module: test_provider_status_discrimination, test_provider_probe_semantics, test_production_registry_is_nvidia_only, test_nvidia_only_error_message, test_f16_multibyte_utf8_secret_masking

src/config/resolved.rs​

Primary Responsibility​

Unified Authoritative Configuration Control Plane (CFG-01..04). Provides the single authoritative ResolvedConfiguration used by the production runtime, enforcing the 8-tier hierarchy: Tier 0: Immutable Security Invariants Tier 1: System Configuration (/etc/m31a/config.toml) Tier 2: User Configuration (~/.config/m31a/config.toml) Tier 3: Workspace Configuration (<workspace>/.m31a/config.toml) Tier 4: Profile (e.g. autonomous, coding, safe) Tier 5: Environment (M31A_*, std::env) Tier 6: CLI (--config, --model, --profile, --autonomy, etc.) Tier 7: Session Override (/model, /profile, runtime dynamic overrides)

Types & Trait Declarations​

  • Structs (4): ConfigExplain, ResolvedConfigBuilder, ResolvedConfiguration, TierOverrideRecord

Key Functions & Signatures (15 shown)​

// pub
fn builder(workspace_root: impl Into<PathBuf>) -> ResolvedConfigBuilder;
// pub
fn for_workspace(workspace_root: impl Into<PathBuf>) -> Result<Self, ConfigError>;
// pub
fn build_fallback(workspace_root: impl Into<PathBuf>) -> Self;
// pub
fn workspace_config_exists(workspace_root: impl Into<PathBuf>) -> bool;
// pub
fn load_strict(workspace_root: impl Into<PathBuf>) -> Result<Self, ConfigError>;
// pub
fn get_resolved(&self, key: &str) -> Option<ResolvedValue>;
// pub
fn explain(&self, key: &str) -> Option<ConfigExplain>;
// pub
fn sources(&self) -> Vec<String>;
// pub
fn with_session_model(&self, model: &str) -> Result<Self, ConfigError>;
// pub
fn with_session_provider(&self, provider: &str) -> Result<Self, ConfigError>;
// pub
fn active_provider_status(&self) -> crate::model::types::ProviderCapabilityStatus;
// pub
fn provider_endpoint_source(&self) -> crate::model::provider::EndpointTrustSource;
// pub
fn timeout_policy(&self) -> crate::config::canonical::TimeoutPolicy;
// pub
fn resource_policy(&self) -> crate::config::canonical::ResourcePolicy;
// pub
fn cache_policy(&self) -> crate::config::canonical::ModelCatalogCachePolicy;

src/config/schema.rs​

Primary Responsibility​

Strict Configuration Schema & Validation (CFG-02, D-13).

Types & Trait Declarations​

  • Structs (14): AgentsConfig, AppConfig, CacheConfig, GitConfig, PolicyConfig, ProviderConfig, ProviderTableConfig, ResourcesConfig, RuntimeConfig, TimeoutsConfig, TuiConfig, WorkflowConfig, WorkspaceConfig, WorkspaceVerificationConfig
  • Enums (3): ConfigValidationError, GitExecutionIsolation, GitPushPolicy

Key Functions & Signatures (15 shown)​

// private
fn default_concurrency_limit() -> usize;
// private
fn default_timeout_secs() -> u64;
// private
fn default_sandbox_mode() -> String;
// private
fn default_true() -> bool;
// private
fn default_default_action() -> String;
// private
fn default_model() -> String;
// private
fn default_max_tokens() -> u32;
// private
fn default_fps() -> u32;
// private
fn default_theme() -> String;
// private
fn default_retention_policy() -> String;
// private
fn default_branch_prefix() -> String;
// private
fn default_provider() -> String;
// private
fn default_ignored_paths() -> Vec<String>;
// private
fn default_research_concurrency() -> usize;
// private
fn default_max_discovery_turns() -> usize;