feat(schema): from_resolved_toml + validate (#4)

Chunk M1-W1-B of M1 plan. Lands the two pure functions Plan §6.1 calls
out, plus four canonical fixtures and 12 unit tests.

pub fn from_resolved_toml(s: &str) -> Result<DeclaredState, SchemaError>:
- Single-shot toml::from_str into DeclaredState. The existing
  SchemaError::InvalidToml variant wraps toml::de::Error via #[from],
  so the implementation is a one-liner; the value is in fixtures
  + error-path tests.

pub fn validate(d: &DeclaredState) -> Result<(), Vec<ContractViolation>>:
- DUPLICATE_PACKAGES — every package name appears in at most one list
  across PackageSet and the two RemovePolicy lists. Violations name
  every list the duplicate appeared in.
- KERNEL_MODULES_NOT_UNIQUE — kernel.modules and kernel.blacklist
  each contain unique entries, and the two are disjoint.
- ARCH_LEVEL_MISMATCH — meta.arch_level = "v3" forbids a non-empty
  packages.cachyos-v4, and symmetrically. (PRD §6.2 makes this
  relationship explicit; Plan §6.1 listed only the first two
  contracts but this is in the same spirit.)

validate() collects every violation rather than returning the first.

Fixtures (fixtures/schema/):
- host_minimal.toml — meta + kernel.package only.
- host_full.toml — every section populated, two users (one with HM,
  one without), two config entries, custom snapshots.keep.
- host_invalid_arch.toml — bogus arch_level = "v5".
- host_malformed_mode.toml — mode as a string instead of an integer.

Tests:
- parse: parse_minimal_succeeds, parse_full_succeeds,
  reject_invalid_arch_level, reject_malformed_mode.
- validate: validate_clean_minimal, validate_clean_full_fixture,
  validate_duplicate_packages, validate_kernel_modules_overlap,
  validate_kernel_modules_duplicate_within_list,
  validate_arch_level_v3_with_v4_packages,
  validate_arch_level_v4_with_v3_packages,
  validate_collects_multiple_violations.

What's NOT in this chunk:
- Property tests (chunk M1-W1-C with proptest).
- JsonSchema Draft-2020-12 fixture (chunk M1-W1-C).

Verification:
- cargo test -p pearlite-schema  (12 passed; 0 failed)
- cargo clippy --workspace --all-targets -- -D warnings  (zero warnings)
- cargo fmt --all --check
- scripts/ci/check-spdx.sh
- pearlite-audit check .  (1 check, 0 violations)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

crates/pearlite-schema/src/errors.rs

@@ -17,7 +17,7 @@ pub enum SchemaError {
     MissingHostFile(PathBuf),
 }
 
-/// One contract violation produced by `validate` (lands in chunk M1-W1-B).
+/// One contract violation produced by [`validate`](crate::validate).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ContractViolation {
     /// Stable contract identifier (e.g. `DUPLICATE_PACKAGES`).
@@ -26,6 +26,17 @@ pub struct ContractViolation {
     pub message: String,
 }
 
+impl ContractViolation {
+    /// A package name appears in more than one declared list.
+    pub const DUPLICATE_PACKAGES: &'static str = "DUPLICATE_PACKAGES";
+    /// A kernel module appears more than once, or appears in both
+    /// `kernel.modules` and `kernel.blacklist`.
+    pub const KERNEL_MODULES_NOT_UNIQUE: &'static str = "KERNEL_MODULES_NOT_UNIQUE";
+    /// `meta.arch_level` does not match the declared per-feature-level
+    /// repository: e.g. `arch_level = "v3"` with non-empty `packages.cachyos-v4`.
+    pub const ARCH_LEVEL_MISMATCH: &'static str = "ARCH_LEVEL_MISMATCH";
+}
+
 impl std::fmt::Display for ContractViolation {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}: {}", self.id, self.message)

crates/pearlite-schema/src/lib.rs

@@ -15,20 +15,24 @@ mod declared;
 mod errors;
 mod host;
 mod packages;
+mod parse;
 mod probed;
 mod services;
 mod snapshots;
 mod users;
+mod validate;
 
 pub use config::{ConfigEntry, RemovePolicy};
 pub use declared::DeclaredState;
 pub use errors::{ContractViolation, SchemaError};
 pub use host::{ArchLevel, HostMeta, KernelDecl};
 pub use packages::PackageSet;
+pub use parse::from_resolved_toml;
 pub use probed::{
     CargoInventory, ConfigFileInventory, ConfigFileMeta, HostInfo, KernelInfo, PacmanInventory,
     ProbedState, ServiceInventory,
 };
 pub use services::ServicesDecl;
 pub use snapshots::SnapshotPolicy;
 pub use users::{HomeManagerDecl, HomeManagerMode, UserDecl};
+pub use validate::validate;

crates/pearlite-schema/src/parse.rs

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! Resolved-TOML to [`DeclaredState`] parsing.
+
+use crate::declared::DeclaredState;
+use crate::errors::SchemaError;
+
+/// Parse a resolved-TOML host configuration into [`DeclaredState`].
+///
+/// The input is the stdout of `nickel export -f toml <host_file>`, captured
+/// by `pearlite-nickel`. This function is pure — it never reads the
+/// filesystem or spawns a subprocess. Cross-field invariants are not
+/// checked here; call [`crate::validate`] on the result before relying on
+/// the value.
+///
+/// # Errors
+/// Returns [`SchemaError::InvalidToml`] when the input is not well-formed
+/// TOML or when a field type or enum variant does not match the schema.
+pub fn from_resolved_toml(s: &str) -> Result<DeclaredState, SchemaError> {
+    toml::from_str::<DeclaredState>(s).map_err(SchemaError::from)
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::panic,
+    reason = "tests may use expect()/unwrap()/panic!() per Plan §4.2 + CLAUDE.md"
+)]
+mod tests {
+    use super::*;
+    use crate::host::ArchLevel;
+
+    const MINIMAL: &str = include_str!("../../../fixtures/schema/host_minimal.toml");
+    const FULL: &str = include_str!("../../../fixtures/schema/host_full.toml");
+    const INVALID_ARCH: &str = include_str!("../../../fixtures/schema/host_invalid_arch.toml");
+    const MALFORMED_MODE: &str = include_str!("../../../fixtures/schema/host_malformed_mode.toml");
+
+    #[test]
+    fn parse_minimal_succeeds() {
+        let d = from_resolved_toml(MINIMAL).expect("minimal fixture parses");
+        assert_eq!(d.host.hostname, "forge");
+        assert_eq!(d.host.arch_level, ArchLevel::V4);
+        assert_eq!(d.kernel.package, "linux-cachyos");
+        assert!(d.packages.core.is_empty());
+        assert!(d.config_files.is_empty());
+        assert!(d.users.is_empty());
+    }
+
+    #[test]
+    fn parse_full_succeeds() {
+        let d = from_resolved_toml(FULL).expect("full fixture parses");
+        assert_eq!(d.host.hostname, "forge");
+        assert_eq!(d.host.locale, "en_GB.UTF-8");
+        assert_eq!(d.kernel.cmdline.len(), 3);
+        assert_eq!(d.kernel.modules.len(), 4);
+        assert_eq!(d.kernel.blacklist, vec!["nouveau".to_owned()]);
+        assert_eq!(d.packages.core.len(), 3);
+        assert_eq!(d.packages.cachyos_v4.len(), 3);
+        assert_eq!(d.packages.aur.len(), 2);
+        assert_eq!(d.config_files.len(), 2);
+        assert_eq!(d.config_files[0].mode, 384); // 0o600
+        assert_eq!(d.config_files[1].mode, 0o644); // default
+        assert_eq!(d.services.enabled.len(), 2);
+        assert_eq!(d.users.len(), 2);
+        assert!(d.users[0].home_manager.is_some());
+        assert!(d.users[1].home_manager.is_none());
+        assert_eq!(d.remove.packages, vec!["xterm".to_owned()]);
+        assert_eq!(d.snapshots.keep, 30);
+    }
+
+    #[test]
+    fn reject_invalid_arch_level() {
+        let err = from_resolved_toml(INVALID_ARCH).expect_err("v5 must be rejected at parse time");
+        assert!(matches!(err, SchemaError::InvalidToml(_)), "got {err:?}");
+    }
+
+    #[test]
+    fn reject_malformed_mode() {
+        let err = from_resolved_toml(MALFORMED_MODE)
+            .expect_err("string mode must be rejected at parse time");
+        assert!(matches!(err, SchemaError::InvalidToml(_)), "got {err:?}");
+    }
+}

crates/pearlite-schema/src/validate.rs

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! Cross-field contract checks for [`DeclaredState`].
+
+use crate::declared::DeclaredState;
+use crate::errors::ContractViolation;
+use crate::host::ArchLevel;
+use std::collections::BTreeMap;
+
+/// Check cross-field contracts on a parsed host configuration.
+///
+/// Serde catches type and enum errors at parse time. This function adds
+/// the invariants serde cannot express:
+///
+/// - **`DUPLICATE_PACKAGES`** — every package name appears in at most one
+///   list across [`PackageSet`](crate::PackageSet),
+///   [`RemovePolicy::packages`](crate::RemovePolicy), and
+///   [`RemovePolicy::ignore`](crate::RemovePolicy).
+/// - **`KERNEL_MODULES_NOT_UNIQUE`** — `kernel.modules` and
+///   `kernel.blacklist` each contain unique entries, and the two sets are
+///   disjoint.
+/// - **`ARCH_LEVEL_MISMATCH`** — `meta.arch_level = "v3"` forbids a
+///   non-empty `packages.cachyos-v4`, and symmetrically.
+///
+/// # Errors
+/// Returns every violation found, not just the first.
+pub fn validate(d: &DeclaredState) -> Result<(), Vec<ContractViolation>> {
+    let mut violations = Vec::new();
+    check_duplicate_packages(d, &mut violations);
+    check_kernel_modules_unique(d, &mut violations);
+    check_arch_level_matches_packages(d, &mut violations);
+    if violations.is_empty() {
+        Ok(())
+    } else {
+        Err(violations)
+    }
+}
+
+fn check_duplicate_packages(d: &DeclaredState, violations: &mut Vec<ContractViolation>) {
+    let p = &d.packages;
+    let lists: [(&str, &[String]); 8] = [
+        ("packages.core", &p.core),
+        ("packages.cachyos", &p.cachyos),
+        ("packages.cachyos-v3", &p.cachyos_v3),
+        ("packages.cachyos-v4", &p.cachyos_v4),
+        ("packages.aur", &p.aur),
+        ("packages.cargo", &p.cargo),
+        ("remove.packages", &d.remove.packages),
+        ("remove.ignore", &d.remove.ignore),
+    ];
+
+    let mut seen: BTreeMap<String, Vec<&str>> = BTreeMap::new();
+    for (label, items) in lists {
+        for name in items {
+            seen.entry(name.clone()).or_default().push(label);
+        }
+    }
+
+    for (name, sources) in seen {
+        if sources.len() > 1 {
+            violations.push(ContractViolation {
+                id: ContractViolation::DUPLICATE_PACKAGES,
+                message: format!("'{}' appears in {}", name, sources.join(", ")),
+            });
+        }
+    }
+}
+
+fn check_kernel_modules_unique(d: &DeclaredState, violations: &mut Vec<ContractViolation>) {
+    let modules = &d.kernel.modules;
+    let blacklist = &d.kernel.blacklist;
+
+    if let Some(dup) = first_duplicate(modules) {
+        violations.push(ContractViolation {
+            id: ContractViolation::KERNEL_MODULES_NOT_UNIQUE,
+            message: format!("'{dup}' appears more than once in kernel.modules"),
+        });
+    }
+    if let Some(dup) = first_duplicate(blacklist) {
+        violations.push(ContractViolation {
+            id: ContractViolation::KERNEL_MODULES_NOT_UNIQUE,
+            message: format!("'{dup}' appears more than once in kernel.blacklist"),
+        });
+    }
+
+    for name in modules {
+        if blacklist.contains(name) {
+            violations.push(ContractViolation {
+                id: ContractViolation::KERNEL_MODULES_NOT_UNIQUE,
+                message: format!("'{name}' appears in both kernel.modules and kernel.blacklist"),
+            });
+        }
+    }
+}
+
+fn check_arch_level_matches_packages(d: &DeclaredState, violations: &mut Vec<ContractViolation>) {
+    match d.host.arch_level {
+        ArchLevel::V3 if !d.packages.cachyos_v4.is_empty() => {
+            violations.push(ContractViolation {
+                id: ContractViolation::ARCH_LEVEL_MISMATCH,
+                message: "meta.arch_level = 'v3' but packages.cachyos-v4 is non-empty".to_owned(),
+            });
+        }
+        ArchLevel::V4 if !d.packages.cachyos_v3.is_empty() => {
+            violations.push(ContractViolation {
+                id: ContractViolation::ARCH_LEVEL_MISMATCH,
+                message: "meta.arch_level = 'v4' but packages.cachyos-v3 is non-empty".to_owned(),
+            });
+        }
+        _ => {}
+    }
+}
+
+fn first_duplicate(items: &[String]) -> Option<&str> {
+    let mut seen = std::collections::BTreeSet::new();
+    for item in items {
+        if !seen.insert(item.as_str()) {
+            return Some(item.as_str());
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::panic,
+    reason = "tests may use expect()/unwrap()/panic!() per Plan §4.2 + CLAUDE.md"
+)]
+mod tests {
+    use super::*;
+    use crate::parse::from_resolved_toml;
+
+    const MINIMAL: &str = include_str!("../../../fixtures/schema/host_minimal.toml");
+    const FULL: &str = include_str!("../../../fixtures/schema/host_full.toml");
+
+    #[test]
+    fn validate_clean_minimal() {
+        let d = from_resolved_toml(MINIMAL).expect("parse");
+        assert!(validate(&d).is_ok());
+    }
+
+    #[test]
+    fn validate_clean_full_fixture() {
+        let d = from_resolved_toml(FULL).expect("parse");
+        validate(&d).expect("full fixture must satisfy every contract");
+    }
+
+    #[test]
+    fn validate_duplicate_packages() {
+        let mut d = from_resolved_toml(MINIMAL).expect("parse");
+        d.packages.core.push("htop".to_owned());
+        d.packages.aur.push("htop".to_owned());
+
+        let err = validate(&d).expect_err("duplicate must be flagged");
+        assert_eq!(err.len(), 1);
+        assert_eq!(err[0].id, ContractViolation::DUPLICATE_PACKAGES);
+        assert!(err[0].message.contains("htop"));
+        assert!(err[0].message.contains("packages.core"));
+        assert!(err[0].message.contains("packages.aur"));
+    }
+
+    #[test]
+    fn validate_kernel_modules_overlap() {
+        let mut d = from_resolved_toml(MINIMAL).expect("parse");
+        d.kernel.modules = vec!["nvidia".to_owned(), "nouveau".to_owned()];
+        d.kernel.blacklist = vec!["nouveau".to_owned()];
+
+        let err = validate(&d).expect_err("overlap must be flagged");
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::KERNEL_MODULES_NOT_UNIQUE
+                    && v.message.contains("nouveau")
+                    && v.message.contains("kernel.modules")
+                    && v.message.contains("kernel.blacklist"))
+        );
+    }
+
+    #[test]
+    fn validate_kernel_modules_duplicate_within_list() {
+        let mut d = from_resolved_toml(MINIMAL).expect("parse");
+        d.kernel.modules = vec!["nvidia".to_owned(), "nvidia".to_owned()];
+
+        let err = validate(&d).expect_err("duplicate must be flagged");
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::KERNEL_MODULES_NOT_UNIQUE
+                    && v.message.contains("nvidia"))
+        );
+    }
+
+    #[test]
+    fn validate_arch_level_v3_with_v4_packages() {
+        let mut d = from_resolved_toml(MINIMAL).expect("parse");
+        d.host.arch_level = ArchLevel::V3;
+        d.packages.cachyos_v4 = vec!["firefox".to_owned()];
+
+        let err = validate(&d).expect_err("arch-level mismatch must be flagged");
+        assert_eq!(err.len(), 1);
+        assert_eq!(err[0].id, ContractViolation::ARCH_LEVEL_MISMATCH);
+    }
+
+    #[test]
+    fn validate_arch_level_v4_with_v3_packages() {
+        let mut d = from_resolved_toml(MINIMAL).expect("parse");
+        d.host.arch_level = ArchLevel::V4;
+        d.packages.cachyos_v3 = vec!["openssl".to_owned()];
+
+        let err = validate(&d).expect_err("arch-level mismatch must be flagged");
+        assert_eq!(err.len(), 1);
+        assert_eq!(err[0].id, ContractViolation::ARCH_LEVEL_MISMATCH);
+    }
+
+    #[test]
+    fn validate_collects_multiple_violations() {
+        let mut d = from_resolved_toml(MINIMAL).expect("parse");
+        d.packages.core.push("htop".to_owned());
+        d.packages.aur.push("htop".to_owned());
+        d.kernel.modules = vec!["x".to_owned(), "x".to_owned()];
+
+        let err = validate(&d).expect_err("two violations expected");
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::DUPLICATE_PACKAGES)
+        );
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::KERNEL_MODULES_NOT_UNIQUE)
+        );
+    }
+}