v0.1.3-pre.008

crates/ksp-config-lib/src/document.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-config-lib/src/document.rs
-// version: 1
+// version: 2
 
 /// A Config-managed JSON document that has passed syntax, schema and current semantic validation.
 #[derive(Clone, Debug, PartialEq)]
@@ -208,6 +208,10 @@ fn validate_instance(document: &ConfigJsonDocument, schema: &ConfigJsonDocument)
 }
 
 fn validate_document_semantics(document: &ConfigJsonDocument) -> ksp_core_lib::Result<()> {
+    let profile_validation = crate::profile::validate_document_profile_contract(document);
+    if let std::result::Result::Err(error) = profile_validation {
+        return std::result::Result::Err(error);
+    }
     if document.file_id().as_str() != crate::FILE_ID_STD_LOGGING {
         return std::result::Result::Ok(());
     }

crates/ksp-config-lib/src/error.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-config-lib/src/error.rs
-// version: 3
+// version: 4
 
 /// Error code used when a Config bootstrap argument is missing its value.
 pub const ERROR_CODE_BOOTSTRAP_ARGUMENT_MISSING_VALUE: ksp_core_lib::ErrorCode = ksp_core_lib::ErrorCode::new("config", "bootstrap_argument_missing_value");
@@ -33,3 +33,6 @@ pub const ERROR_CODE_SCHEMA_VALIDATION_FAILED: ksp_core_lib::ErrorCode = ksp_cor
 
 /// Error code used when a schema-valid Config document violates KSP semantic invariants for its document type.
 pub const ERROR_CODE_DOCUMENT_SEMANTIC_INVALID: ksp_core_lib::ErrorCode = ksp_core_lib::ErrorCode::new("config", "document_semantic_invalid");
+
+/// Error code used when an explicitly requested Config profile does not exist in a validated document.
+pub const ERROR_CODE_PROFILE_NOT_FOUND: ksp_core_lib::ErrorCode = ksp_core_lib::ErrorCode::new("config", "profile_not_found");

crates/ksp-config-lib/src/lib.rs

@@ -1,18 +1,19 @@
 // file: crates/ksp-config-lib/src/lib.rs
-// version: 3
+// version: 4
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
 #![forbid(unsafe_code)]
 
 //! KSP-owned application configuration facade.
 //!
-//! `0.1.3-pre.007` owns the non-recursive bootstrap roots, stable logical file registry and first generic JSON/JSON Schema loading pipeline. The standard
-//! Logging document is the first registered runtime document. Profile resolution, environment substitution, sensitivity and persistence remain in later bounded
+//! `0.1.3-pre.008` owns bootstrap roots, the logical file registry, generic JSON/JSON Schema loading and standard-document profile resolution. The standard
+//! Logging document is the first registered runtime document. Composite resolution, environment substitution, sensitivity and persistence remain in later bounded
 //! prereleases.
 
 mod bootstrap;
 mod document;
 mod error;
+mod profile;
 mod registry;
 
 /// Bootstrap argument used to replace the configuration document root.
@@ -47,10 +48,18 @@ pub use self::error::ERROR_CODE_FILE_MAPPING_INVALID;
 pub use self::error::ERROR_CODE_JSON_FILE_READ_FAILED;
 /// Error code used when a Config-managed file contains invalid JSON syntax.
 pub use self::error::ERROR_CODE_JSON_SYNTAX_INVALID;
+/// Error code used when an explicitly requested Config profile does not exist.
+pub use self::error::ERROR_CODE_PROFILE_NOT_FOUND;
 /// Error code used when a JSON Schema document is itself invalid.
 pub use self::error::ERROR_CODE_SCHEMA_INVALID;
 /// Error code used when a Config document fails its registered JSON Schema validation.
 pub use self::error::ERROR_CODE_SCHEMA_VALIDATION_FAILED;
+/// Source that selected an effective standard Config profile.
+pub use self::profile::ConfigProfileSelectionSource;
+/// Origin of one top-level value in a resolved standard Config profile.
+pub use self::profile::ConfigValueOrigin;
+/// Validated standard Config document resolved to one profile with global/profile provenance.
+pub use self::profile::ResolvedConfigProfile;
 /// Bootstrap argument used to replace a known Config filename mapping.
 pub use self::registry::ARG_FILE_MAP;
 /// Logical descriptor associating a stable file identifier with its physical filename and validation schema.

crates/ksp-config-lib/src/profile.rs

@@ -0,0 +1,236 @@
+// file: crates/ksp-config-lib/src/profile.rs
+// version: 1
+
+/// Origin of one top-level value in a resolved standard Config profile.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ConfigValueOrigin {
+    /// Value comes from the global section of the specialized document.
+    Global,
+    /// Value comes from the selected profile object.
+    Profile,
+}
+
+/// Source that selected the effective profile.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ConfigProfileSelectionSource {
+    /// The document's autonomous `default_profile` selected the profile.
+    DefaultProfile,
+    /// A caller explicitly requested the profile by `profile_id`.
+    Explicit,
+}
+
+/// Validated standard document resolved to one profile while retaining global/profile provenance.
+#[derive(Clone, Debug, PartialEq)]
+pub struct ResolvedConfigProfile {
+    file_id: crate::ConfigFileId,
+    path: std::path::PathBuf,
+    profile_id: String,
+    selection_source: ConfigProfileSelectionSource,
+    globals: serde_json::Map<String, serde_json::Value>,
+    profile: serde_json::Map<String, serde_json::Value>,
+    effective: serde_json::Map<String, serde_json::Value>,
+    origins: std::collections::BTreeMap<String, ConfigValueOrigin>,
+}
+
+impl ResolvedConfigProfile {
+    /// Returns the logical document identifier from which this profile was resolved.
+    #[must_use]
+    pub fn file_id(&self) -> &crate::ConfigFileId {
+        return &self.file_id;
+    }
+
+    /// Returns the physical path of the validated source document.
+    #[must_use]
+    pub fn path(&self) -> &std::path::Path {
+        return self.path.as_path();
+    }
+
+    /// Returns the selected unique profile identifier.
+    #[must_use]
+    pub fn profile_id(&self) -> &str {
+        return self.profile_id.as_str();
+    }
+
+    /// Returns whether selection came from `default_profile` or an explicit caller request.
+    #[must_use]
+    pub const fn selection_source(&self) -> ConfigProfileSelectionSource {
+        return self.selection_source;
+    }
+
+    /// Returns document-global values, excluding the reserved `default_profile` and `profiles` keys.
+    #[must_use]
+    pub fn globals(&self) -> &serde_json::Map<String, serde_json::Value> {
+        return &self.globals;
+    }
+
+    /// Returns the selected profile object including its `profile_id`.
+    #[must_use]
+    pub fn profile(&self) -> &serde_json::Map<String, serde_json::Value> {
+        return &self.profile;
+    }
+
+    /// Returns a deterministic top-level effective view in which selected profile keys override same-named global keys.
+    #[must_use]
+    pub fn effective(&self) -> &serde_json::Map<String, serde_json::Value> {
+        return &self.effective;
+    }
+
+    /// Returns the top-level provenance for an effective key.
+    #[must_use]
+    pub fn origin(&self, key: &str) -> std::option::Option<ConfigValueOrigin> {
+        return self.origins.get(key).copied();
+    }
+}
+
+impl crate::ConfigDocumentEngine {
+    /// Loads, validates and resolves one standard Config document to its default or explicitly requested profile.
+    ///
+    /// Passing `None` selects the autonomous `default_profile` declared by the document. Passing `Some(profile_id)` selects that profile explicitly.
+    /// Environment interpolation and composite overrides are intentionally not applied by this prerelease.
+    pub fn load_resolved_profile(
+        &self,
+        file_id: &crate::ConfigFileId,
+        requested_profile: std::option::Option<&str>,
+    ) -> ksp_core_lib::Result<ResolvedConfigProfile> {
+        let document = self.load_validated_document(file_id);
+        let document = match document {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        return resolve_document_profile(&document, requested_profile);
+    }
+}
+
+pub(crate) fn validate_document_profile_contract(document: &crate::ConfigJsonDocument) -> ksp_core_lib::Result<()> {
+    let root = match document.value().as_object() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Ok(()),
+    };
+    let default_profile = root.get("default_profile");
+    let profiles = root.get("profiles");
+    if default_profile.is_none() && profiles.is_none() {
+        return std::result::Result::Ok(());
+    }
+    let default_profile = match default_profile.and_then(serde_json::Value::as_str) {
+        std::option::Option::Some(value) if !value.trim().is_empty() => value,
+        _ => return std::result::Result::Err(profile_semantic_error(document, "default_profile must identify a non-empty profile_id")),
+    };
+    let profiles = match profiles.and_then(serde_json::Value::as_array) {
+        std::option::Option::Some(value) if !value.is_empty() => value,
+        _ => return std::result::Result::Err(profile_semantic_error(document, "profiles must contain at least one profile object")),
+    };
+    let mut ids = std::collections::BTreeSet::<String>::new();
+    let mut default_found = false;
+    for (index, profile) in profiles.iter().enumerate() {
+        let object = match profile.as_object() {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => {
+                return std::result::Result::Err(
+                    profile_semantic_error(document, "profile entry must be an object").with_context("profile_index", index.to_string()),
+                );
+            },
+        };
+        let profile_id = match object.get("profile_id").and_then(serde_json::Value::as_str) {
+            std::option::Option::Some(value) if !value.trim().is_empty() => value,
+            _ => {
+                return std::result::Result::Err(
+                    profile_semantic_error(document, "profile entry must declare a non-empty profile_id").with_context("profile_index", index.to_string()),
+                );
+            },
+        };
+        if ids.contains(profile_id) {
+            return std::result::Result::Err(
+                profile_semantic_error(document, "profile_id values must be unique")
+                    .with_context("profile_index", index.to_string())
+                    .with_context("profile_id", profile_id),
+            );
+        }
+        ids.insert(profile_id.to_owned());
+        if profile_id == default_profile {
+            default_found = true;
+        }
+    }
+    if !default_found {
+        return std::result::Result::Err(
+            profile_semantic_error(document, "default_profile must reference an existing profile_id").with_context("default_profile", default_profile),
+        );
+    }
+    return std::result::Result::Ok(());
+}
+
+fn resolve_document_profile(document: &crate::ConfigJsonDocument, requested_profile: std::option::Option<&str>) -> ksp_core_lib::Result<ResolvedConfigProfile> {
+    let root = match document.value().as_object() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Err(profile_semantic_error(document, "profile resolution requires an object document")),
+    };
+    let default_profile = match root.get("default_profile").and_then(serde_json::Value::as_str) {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Err(profile_semantic_error(document, "profile resolution requires default_profile")),
+    };
+    let (selected_profile, selection_source) = match requested_profile {
+        std::option::Option::Some(value) => (value, ConfigProfileSelectionSource::Explicit),
+        std::option::Option::None => (default_profile, ConfigProfileSelectionSource::DefaultProfile),
+    };
+    let profiles = match root.get("profiles").and_then(serde_json::Value::as_array) {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Err(profile_semantic_error(document, "profile resolution requires profiles")),
+    };
+    let mut selected: std::option::Option<&serde_json::Map<String, serde_json::Value>> = std::option::Option::None;
+    for profile in profiles {
+        let object = match profile.as_object() {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => continue,
+        };
+        if object.get("profile_id").and_then(serde_json::Value::as_str) == std::option::Option::Some(selected_profile) {
+            selected = std::option::Option::Some(object);
+            break;
+        }
+    }
+    let selected = match selected {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => {
+            return std::result::Result::Err(
+                ksp_core_lib::Error::new(crate::ERROR_CODE_PROFILE_NOT_FOUND, "requested Config profile does not exist")
+                    .with_context("file_id", document.file_id().as_str())
+                    .with_context("path", document.path().to_string_lossy().into_owned())
+                    .with_context("profile_id", selected_profile),
+            );
+        },
+    };
+    let mut globals = serde_json::Map::<String, serde_json::Value>::new();
+    let mut effective = serde_json::Map::<String, serde_json::Value>::new();
+    let mut origins = std::collections::BTreeMap::<String, ConfigValueOrigin>::new();
+    for (key, value) in root {
+        if key != "default_profile" && key != "profiles" {
+            globals.insert(key.clone(), value.clone());
+            effective.insert(key.clone(), value.clone());
+            origins.insert(key.clone(), ConfigValueOrigin::Global);
+        }
+    }
+    let profile = (*selected).clone();
+    for (key, value) in &profile {
+        effective.insert(key.clone(), value.clone());
+        origins.insert(key.clone(), ConfigValueOrigin::Profile);
+    }
+    return std::result::Result::Ok(ResolvedConfigProfile {
+        file_id: document.file_id().clone(),
+        path: document.path().to_path_buf(),
+        profile_id: selected_profile.to_owned(),
+        selection_source,
+        globals,
+        profile,
+        effective,
+        origins,
+    });
+}
+
+fn profile_semantic_error(document: &crate::ConfigJsonDocument, reason: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_DOCUMENT_SEMANTIC_INVALID, "Config document violates KSP profile invariants")
+        .with_context("file_id", document.file_id().as_str())
+        .with_context("path", document.path().to_string_lossy().into_owned())
+        .with_context("reason", reason);
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/profile.rs"]
+mod tests;