feat(schema): nix.installer.expected_sha256 + NIX_INSTALLER_REQUIRED contract (#55)

Adds the per-host Nix bootstrap declaration that ADR-0012 routes
through `pearlite bootstrap`: the Determinate installer's SHA-256
pin lives next to the consumer (the host that needs it), not in a
repo-wide bootstrap file.

- New `pearlite_schema::NixDecl` and `NixInstallerDecl` types in
  `nix.rs`. Wired through `lib.rs` and as `DeclaredState::nix:
  Option<NixDecl>` (default None).
- New cross-field contract `NIX_INSTALLER_REQUIRED`: when any user
  has `home_manager.enabled = true`, the host's
  `nix.installer.expected_sha256` must be present and well-formed
  (64 lowercase hex chars). HM-disabled hosts may omit the block.
- `host_full.toml` fixture grows a `[nix.installer]` table so the
  pre-existing `validate_clean_full_fixture` keeps passing under
  the new contract.
- Four new validator tests covering the four cases (missing block
  with HM, malformed sha, uppercase hex, HM-disabled-everywhere).

Tests: 307 passing (was 303, +4). Clippy clean. fmt clean. audit clean.

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

Author: UnbreakableMJ

crates/pearlite-diff/src/compose.rs

@@ -350,6 +350,7 @@ mod tests {
             users: Vec::new(),
             remove: pearlite_schema::RemovePolicy::default(),
             snapshots: pearlite_schema::SnapshotPolicy::default(),
+            nix: None,
         }
     }
 

crates/pearlite-schema/src/declared.rs

@@ -8,6 +8,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::config::{ConfigEntry, RemovePolicy};
 use crate::host::{HostMeta, KernelDecl};
+use crate::nix::NixDecl;
 use crate::packages::PackageSet;
 use crate::services::ServicesDecl;
 use crate::snapshots::SnapshotPolicy;
@@ -44,4 +45,9 @@ pub struct DeclaredState {
     /// Snapshot retention policy.
     #[serde(default)]
     pub snapshots: SnapshotPolicy,
+    /// Optional nix bootstrap declaration. Required by the schema
+    /// validator iff any user has `home_manager.enabled = true` —
+    /// see [`ContractViolation::NIX_INSTALLER_REQUIRED`](crate::ContractViolation).
+    #[serde(default)]
+    pub nix: Option<NixDecl>,
 }

crates/pearlite-schema/src/errors.rs

@@ -35,6 +35,10 @@ impl ContractViolation {
     /// `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";
+    /// At least one user has `home_manager.enabled = true` but the
+    /// `nix.installer.expected_sha256` pin is missing or malformed
+    /// (must be 64 lowercase hex chars). See ADR-0012.
+    pub const NIX_INSTALLER_REQUIRED: &'static str = "NIX_INSTALLER_REQUIRED";
 }
 
 impl std::fmt::Display for ContractViolation {

crates/pearlite-schema/src/lib.rs

@@ -14,6 +14,7 @@ mod config;
 mod declared;
 mod errors;
 mod host;
+mod nix;
 mod packages;
 mod parse;
 mod probed;
@@ -26,6 +27,7 @@ pub use config::{ConfigEntry, RemovePolicy};
 pub use declared::DeclaredState;
 pub use errors::{ContractViolation, SchemaError};
 pub use host::{ArchLevel, HostMeta, KernelDecl};
+pub use nix::{NixDecl, NixInstallerDecl};
 pub use packages::PackageSet;
 pub use parse::from_resolved_toml;
 pub use probed::{

crates/pearlite-schema/src/nix.rs

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! Nix bootstrap declaration block.
+//!
+//! Modeled per ADR-0012 (`docs/adr/0012-nix-bootstrap-wiring.md`):
+//! the per-host Nickel config carries the SHA-256 pin of the
+//! Determinate Nix installer that `pearlite bootstrap` will execute
+//! on first run. The pin lives next to the consumer (the host that
+//! needs nix) rather than in a repo-wide bootstrap file or a
+//! Pearlite-baked release constant.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// Per-host nix bootstrap declaration.
+///
+/// Optional at the [`DeclaredState`](crate::DeclaredState) level: hosts
+/// that don't run Home Manager don't need to declare it. When any user
+/// on the host has `home_manager.enabled = true`, the schema validator
+/// requires this block — see
+/// [`ContractViolation::NIX_INSTALLER_REQUIRED`](crate::ContractViolation).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+pub struct NixDecl {
+    /// Determinate Nix installer pin.
+    pub installer: NixInstallerDecl,
+}
+
+/// SHA-256 pin for the Determinate Nix installer script.
+///
+/// ADR-004 requires the installer-fetch step to verify the script's
+/// content hash before execution. The expected hash is operator-supplied
+/// per host, refreshed when Determinate ships a new installer version.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+pub struct NixInstallerDecl {
+    /// SHA-256 of the installer script body, as 64 lowercase hex
+    /// characters. Verified by
+    /// [`pearlite_userenv::NixInstaller::install`] before the script is
+    /// executed.
+    pub expected_sha256: String,
+}

crates/pearlite-schema/src/validate.rs

@@ -22,6 +22,9 @@ use std::collections::BTreeMap;
 ///   disjoint.
 /// - **`ARCH_LEVEL_MISMATCH`** — `meta.arch_level = "v3"` forbids a
 ///   non-empty `packages.cachyos-v4`, and symmetrically.
+/// - **`NIX_INSTALLER_REQUIRED`** — any user with
+///   `home_manager.enabled = true` requires a present, well-formed
+///   `nix.installer.expected_sha256` (64 lowercase hex chars).
 ///
 /// # Errors
 /// Returns every violation found, not just the first.
@@ -30,6 +33,7 @@ pub fn validate(d: &DeclaredState) -> Result<(), Vec<ContractViolation>> {
     check_duplicate_packages(d, &mut violations);
     check_kernel_modules_unique(d, &mut violations);
     check_arch_level_matches_packages(d, &mut violations);
+    check_nix_installer_required(d, &mut violations);
     if violations.is_empty() {
         Ok(())
     } else {
@@ -112,6 +116,42 @@ fn check_arch_level_matches_packages(d: &DeclaredState, violations: &mut Vec<Con
     }
 }
 
+fn check_nix_installer_required(d: &DeclaredState, violations: &mut Vec<ContractViolation>) {
+    let any_hm_enabled = d
+        .users
+        .iter()
+        .any(|u| u.home_manager.as_ref().is_some_and(|hm| hm.enabled));
+    if !any_hm_enabled {
+        return;
+    }
+    match d.nix.as_ref() {
+        None => {
+            violations.push(ContractViolation {
+                id: ContractViolation::NIX_INSTALLER_REQUIRED,
+                message:
+                    "at least one user has home_manager.enabled = true but [nix.installer] is not declared"
+                        .to_owned(),
+            });
+        }
+        Some(nix) => {
+            let sha = &nix.installer.expected_sha256;
+            if sha.len() != 64
+                || !sha
+                    .bytes()
+                    .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
+            {
+                violations.push(ContractViolation {
+                    id: ContractViolation::NIX_INSTALLER_REQUIRED,
+                    message: format!(
+                        "nix.installer.expected_sha256 must be 64 lowercase hex chars, got {} chars",
+                        sha.len()
+                    ),
+                });
+            }
+        }
+    }
+}
+
 fn first_duplicate(items: &[String]) -> Option<&str> {
     let mut seen = std::collections::BTreeSet::new();
     for item in items {
@@ -213,6 +253,66 @@ mod tests {
         assert_eq!(err[0].id, ContractViolation::ARCH_LEVEL_MISMATCH);
     }
 
+    #[test]
+    fn validate_nix_installer_required_when_hm_enabled_but_block_missing() {
+        let mut d = from_resolved_toml(FULL).expect("parse");
+        d.nix = None;
+
+        let err = validate(&d).expect_err("missing [nix.installer] must be flagged");
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::NIX_INSTALLER_REQUIRED
+                    && v.message.contains("home_manager.enabled = true"))
+        );
+    }
+
+    #[test]
+    fn validate_nix_installer_sha_must_be_64_lowercase_hex() {
+        let mut d = from_resolved_toml(FULL).expect("parse");
+        d.nix = Some(crate::NixDecl {
+            installer: crate::NixInstallerDecl {
+                expected_sha256: "not-hex".to_owned(),
+            },
+        });
+
+        let err = validate(&d).expect_err("malformed sha must be flagged");
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::NIX_INSTALLER_REQUIRED
+                    && v.message.contains("64 lowercase hex chars"))
+        );
+    }
+
+    #[test]
+    fn validate_nix_installer_rejects_uppercase_hex() {
+        let mut d = from_resolved_toml(FULL).expect("parse");
+        let upper = "0123456789ABCDEF0123456789abcdef0123456789abcdef0123456789abcdef";
+        d.nix = Some(crate::NixDecl {
+            installer: crate::NixInstallerDecl {
+                expected_sha256: upper.to_owned(),
+            },
+        });
+
+        let err = validate(&d).expect_err("uppercase hex must be flagged");
+        assert!(
+            err.iter()
+                .any(|v| v.id == ContractViolation::NIX_INSTALLER_REQUIRED)
+        );
+    }
+
+    #[test]
+    fn validate_no_nix_block_required_when_hm_disabled_everywhere() {
+        let mut d = from_resolved_toml(FULL).expect("parse");
+        for user in &mut d.users {
+            if let Some(hm) = user.home_manager.as_mut() {
+                hm.enabled = false;
+            }
+        }
+        d.nix = None;
+
+        validate(&d).expect("HM disabled everywhere → nix block optional");
+    }
+
     #[test]
     fn validate_collects_multiple_violations() {
         let mut d = from_resolved_toml(MINIMAL).expect("parse");

fixtures/schema/host_full.toml

@@ -58,3 +58,6 @@ ignore = ["nano"]
 
 [snapshots]
 keep = 30
+
+[nix.installer]
+expected_sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"