nxd_core/application/

mod.rs

use crate::contract::{
	CanonicalConfig, ErrorCategory, ErrorEnvelope, canonical_json, parse_canonical_config,
	validate_canonical_config,
};
use crate::plan::{PlanEnvelope, parse_plan_envelope, sha256_hex};
use std::collections::{BTreeMap, BTreeSet};
use std::fmt;
use std::fs;
use std::future::Future;
use std::path::Path;

const DEFAULT_PLAN_TTL_SECONDS: u64 = 3600;

pub(crate) fn default_plan_expires_at_unix() -> u64 {
	std::time::SystemTime::now()
		.duration_since(std::time::UNIX_EPOCH)
		.unwrap_or_default()
		.as_secs()
		.saturating_add(DEFAULT_PLAN_TTL_SECONDS)
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum NxdError {
	Io(String),
	InvalidConfig(String),
	StalePrecondition(String),
	PolicyRejected(String),
	Provider(crate::ports::provider::ProviderFailure),
}

impl fmt::Display for NxdError {
	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		match self {
			Self::Io(message) => write!(formatter, "{message}"),
			Self::InvalidConfig(message) => write!(formatter, "{message}"),
			Self::StalePrecondition(message) => write!(formatter, "{message}"),
			Self::PolicyRejected(message) => write!(formatter, "{message}"),
			Self::Provider(failure) => write!(formatter, "{}", failure.safe_message),
		}
	}
}

impl NxdError {
	pub const fn category(&self) -> ErrorCategory {
		match self {
			Self::InvalidConfig(_) => ErrorCategory::InvalidInput,
			Self::Io(_) => ErrorCategory::Operational,
			Self::StalePrecondition(_) => ErrorCategory::StalePrecondition,
			Self::PolicyRejected(_) => ErrorCategory::PolicyRejected,
			Self::Provider(failure) => match failure.category {
				crate::ports::provider::ProviderErrorCategory::InvalidRequest => {
					ErrorCategory::InvalidInput
				}
				crate::ports::provider::ProviderErrorCategory::Incompatible => ErrorCategory::Incompatible,
				crate::ports::provider::ProviderErrorCategory::Cancelled
				| crate::ports::provider::ProviderErrorCategory::Timeout
				| crate::ports::provider::ProviderErrorCategory::Provider
				| crate::ports::provider::ProviderErrorCategory::Transport
				| crate::ports::provider::ProviderErrorCategory::Internal => ErrorCategory::Operational,
			},
		}
	}

	pub const fn exit_code(&self) -> u8 {
		self.category().exit_code()
	}

	pub fn envelope(&self) -> ErrorEnvelope {
		ErrorEnvelope::new(self.category(), self.to_string())
	}

	pub const fn provider_failure(&self) -> Option<&crate::ports::provider::ProviderFailure> {
		match self {
			Self::Provider(failure) => Some(failure),
			_ => None,
		}
	}
}

impl From<serde_json::Error> for NxdError {
	fn from(error: serde_json::Error) -> Self {
		Self::InvalidConfig(error.to_string())
	}
}

pub struct Application {
	/// Canonical inventory loaded by the composition root. Nix target outputs may
	/// be projected out until a lifecycle selection requires them.
	pub(super) config: std::sync::Mutex<Option<CanonicalConfig>>,
	/// External provider and secret executables composed from canonical configuration.
	pub(super) external_runtime: crate::adapters::external_runtime::ExternalRuntimeGraph,
}

/// Async bridge used by provider-protocol and secret-process composition.
/// It performs no provider or transport behavior itself.
struct PveBackupJobRuntime;

impl PveBackupJobRuntime {
	fn async_runtime() -> &'static tokio::runtime::Runtime {
		static RUNTIME: std::sync::OnceLock<tokio::runtime::Runtime> = std::sync::OnceLock::new();
		RUNTIME.get_or_init(|| {
			tokio::runtime::Builder::new_multi_thread()
				.enable_all()
				.thread_name("nxd-async-runtime")
				.build()
				.expect("failed to create NXD async runtime")
		})
	}

	fn run_async<F, T>(future: F) -> Result<T, NxdError>
	where
		F: Future<Output = Result<T, NxdError>> + Send + 'static,
		T: Send + 'static,
	{
		let (result_sender, result_receiver) = std::sync::mpsc::sync_channel(1);
		Self::async_runtime().spawn(async move {
			let _ = result_sender.send(future.await);
		});
		result_receiver
			.recv()
			.map_err(|_| NxdError::Io("NXD async runtime worker dropped its result".to_string()))?
	}
}

fn project_target_outputs(config: &mut CanonicalConfig, requested_hosts: &[String]) {
	let requested = requested_hosts.iter().map(String::as_str).collect::<BTreeSet<_>>();
	for resource in &mut config.spec.resources {
		if let crate::contract::Resource::DeploymentTarget(target) = resource {
			let hostname = target.id.strip_prefix("deployment-target/").unwrap_or(&target.id);
			if !requested.contains(hostname) {
				target.metadata.system_output = None;
				target.metadata.system_derivation = None;
				target.metadata.disko_output = None;
			}
		}
	}
}

#[derive(serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct ResolvedTargetOutput {
	system_output: Option<String>,
	system_derivation: Option<String>,
	disko_output: Option<String>,
}

fn archived_input_paths(archive: &serde_json::Value) -> Result<Vec<String>, NxdError> {
	fn collect(value: &serde_json::Value, paths: &mut BTreeSet<String>) -> Result<(), NxdError> {
		let Some(inputs) = value.get("inputs").and_then(serde_json::Value::as_object) else {
			return Ok(());
		};
		for input in inputs.values() {
			if let Some(path) = input.get("path").and_then(serde_json::Value::as_str) {
				if !path.starts_with("/nix/store/") || path.contains(char::is_control) {
					return Err(NxdError::InvalidConfig(
						"archived evaluation input returned an invalid Nix store path".to_string(),
					));
				}
				paths.insert(path.to_string());
			}
			collect(input, paths)?;
		}
		Ok(())
	}

	let mut paths = BTreeSet::new();
	collect(archive, &mut paths)?;
	Ok(paths.into_iter().collect())
}

/// Whether the archived flake declares the installer-secret input.
///
/// Overriding an input a flake does not declare makes Nix warn and ignore the
/// flag, so consumers without host secrets would carry a staged path nothing
/// reads. Only the root's own inputs count: a transitive dependency declaring
/// the name does not make it overridable on this flake.
fn archive_declares_secret_input(archive: &serde_json::Value) -> bool {
	archive
		.get("inputs")
		.and_then(serde_json::Value::as_object)
		.is_some_and(|inputs| inputs.contains_key(crate::config::SECRET_INPUT_NAME))
}

/// Whether `flake` declares the installer-secret input, read from its lock.
///
/// The local evaluation path stages secrets before anything archives the flake,
/// so it cannot reuse [`archive_declares_secret_input`]. A failed probe reports
/// `true` so a consumer that does declare the input keeps working: a spurious
/// override only warns, whereas a missing one loses the host's secrets.
fn flake_declares_secret_input(flake: &str) -> bool {
	let Ok(output) = crate::process::sanitized_command("nix")
		.args([
			"--extra-experimental-features",
			"nix-command flakes",
			"flake",
			"metadata",
			"--json",
			"--no-write-lock-file",
			flake,
		])
		.output()
	else {
		return true;
	};
	if !output.status.success() {
		return true;
	}
	let Ok(metadata) = serde_json::from_slice::<serde_json::Value>(&output.stdout) else {
		return true;
	};
	metadata
		.pointer("/locks/nodes/root/inputs")
		.and_then(serde_json::Value::as_object)
		.is_some_and(|inputs| inputs.contains_key(crate::config::SECRET_INPUT_NAME))
}

impl Application {
	pub(super) fn current_config(&self) -> Option<CanonicalConfig> {
		self.config.lock().ok()?.clone()
	}

	pub(super) fn update_config(&self, config: &CanonicalConfig) {
		if let Ok(mut guard) = self.config.lock()
			&& guard.is_some()
		{
			*guard = Some(config.clone());
		}
	}

	/// Construct the explicit local-state capability graph used only by
	/// plan-independent show/monitor/approval/artifact-verification operations.
	pub fn local_state() -> Self {
		Self {
			config: std::sync::Mutex::new(None),
			external_runtime: crate::adapters::external_runtime::ExternalRuntimeGraph::default(),
		}
	}

	/// Construct the application from an already-evaluated configuration.
	///
	/// Composition verifies every declared provider/secret executable, records
	/// immutable digests, and refuses missing capabilities. Concrete in-core
	/// PVE/PBS/SOPS runtimes are not constructed here.
	pub fn from_canonical_config(config: &CanonicalConfig) -> Result<Self, NxdError> {
		Self::from_canonical_config_with_linked(
			config,
			&crate::adapters::external_runtime::LinkedProviderRegistry::default(),
		)
	}

	pub fn from_canonical_config_with_linked(
		config: &CanonicalConfig,
		linked: &crate::adapters::external_runtime::LinkedProviderRegistry,
	) -> Result<Self, NxdError> {
		let config = config.clone();
		validate_canonical_config(&config).map_err(|error| NxdError::InvalidConfig(error.0))?;
		let external_runtime =
			crate::adapters::external_runtime::ExternalRuntimeGraph::from_canonical_with_linked(
				&config, linked,
			)
			.map_err(|error| match error {
				crate::adapters::external_runtime::CompositionError::InvalidConfig(message) => {
					NxdError::InvalidConfig(message)
				}
				crate::adapters::external_runtime::CompositionError::MissingExecutable(message)
				| crate::adapters::external_runtime::CompositionError::CapabilityUnavailable(message) => {
					NxdError::InvalidConfig(message)
				}
			})?;
		Ok(Self { config: std::sync::Mutex::new(Some(config)), external_runtime })
	}

	/// Construct the inventory-only application used by canonical read paths.
	///
	/// This validates desired state without composing provider or secret
	/// executables. Operations requiring live observation must use the complete
	/// application graph instead.
	pub fn from_canonical_inventory(config: &CanonicalConfig) -> Result<Self, NxdError> {
		let config = config.clone();
		validate_canonical_config(&config).map_err(|error| NxdError::InvalidConfig(error.0))?;
		Ok(Self {
			config: std::sync::Mutex::new(Some(config)),
			external_runtime: crate::adapters::external_runtime::ExternalRuntimeGraph::default(),
		})
	}

	pub fn external_runtime(&self) -> &crate::adapters::external_runtime::ExternalRuntimeGraph {
		&self.external_runtime
	}

	pub fn from_plan(plan: &PlanEnvelope) -> Result<Self, NxdError> {
		Self::from_plan_with_linked(
			plan,
			&crate::adapters::external_runtime::LinkedProviderRegistry::default(),
		)
	}

	pub fn from_plan_with_linked(
		plan: &PlanEnvelope,
		linked: &crate::adapters::external_runtime::LinkedProviderRegistry,
	) -> Result<Self, NxdError> {
		let external_runtime =
			crate::adapters::external_runtime::ExternalRuntimeGraph::from_plan_with_linked(plan, linked)
				.map_err(|error| NxdError::InvalidConfig(error.to_string()))?;
		Ok(Self { config: std::sync::Mutex::new(None), external_runtime })
	}

	pub fn validate(&self, request: ValidateRequest) -> Result<ValidationReport, NxdError> {
		// Prefer the composed application config (packaging already filled optional
		// packaged provider commands). Re-render only when no composed config is
		// available (e.g. tests that construct Application without composition).
		let config = match self.current_config() {
			Some(config) => config,
			None => Self::render_config(request.source)?,
		};
		validate_canonical_config(&config).map_err(|error| NxdError::InvalidConfig(error.0))?;
		if request.selectors.is_empty() {
			return Ok(ValidationReport::new(config.spec.resources.len()));
		}
		let selection = crate::domain::selection::resolve(&config, &request.selectors)
			.map_err(NxdError::InvalidConfig)?;
		let protocol_selection = provider_lifecycle::classify_protocol_selection(
			&config,
			self.external_runtime(),
			&selection.resource_ids,
		)?
		.ok_or_else(|| {
			NxdError::InvalidConfig("selected resources require configured providers".to_string())
		})?;
		for provider_instance in protocol_selection.by_provider.keys() {
			self
				.external_runtime()
				.require_provider(provider_instance)
				.map_err(|error| NxdError::InvalidConfig(error.to_string()))?;
		}
		Ok(ValidationReport::new(config.spec.resources.len()))
	}

	pub fn render_config(source: ConfigSource) -> Result<CanonicalConfig, NxdError> {
		Self::render_config_projected(source, None)
	}

	/// Load canonical inventory without forcing target build outputs. Lifecycle
	/// planning performs selection against this value before requesting outputs.
	pub fn render_config_inventory(source: ConfigSource) -> Result<CanonicalConfig, NxdError> {
		match source {
			ConfigSource::CanonicalJson(_) => Self::render_config_projected(source, None),
			ConfigSource::NixInstallable(_) => Self::render_config_projected(source, Some(&[])),
		}
	}

	/// Evaluate the lazy canonical inventory for one already-resolved exact
	/// target. Non-install lifecycle commands omit reserved takeover artifacts
	/// before Nix forces their derivations.
	pub fn render_target_inventory(
		source: ConfigSource,
		hostname: &str,
		include_lifecycle_artifacts: bool,
	) -> Result<CanonicalConfig, NxdError> {
		let ConfigSource::NixInstallable(installable) = source else {
			return Self::render_config_inventory(source);
		};
		let (flake, attribute) = installable.rsplit_once('#').ok_or_else(|| {
			NxdError::InvalidConfig(
				"exact target inventory requires an nxdConfigurations.<site> installable".to_string(),
			)
		})?;
		let site = attribute.strip_prefix("nxdConfigurations.").ok_or_else(|| {
			NxdError::InvalidConfig(
				"exact target inventory requires an nxdConfigurations.<site> installable".to_string(),
			)
		})?;
		if hostname.is_empty()
			|| hostname.contains('/')
			|| hostname.contains(char::is_control)
			|| !hostname
				.chars()
				.all(|character| character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.'))
		{
			return Err(NxdError::InvalidConfig(format!(
				"invalid exact target inventory hostname {hostname:?}"
			)));
		}
		let hostname_attribute = serde_json::to_string(hostname)?;
		let target_installable = format!("{flake}#nxdTargetInventories.{site}.{hostname_attribute}");
		let mut command = crate::process::sanitized_command("nix");
		command.args([
			"--extra-experimental-features",
			"nix-command flakes",
			"eval",
			"--json",
			"--impure",
			"--no-eval-cache",
			"--no-write-lock-file",
		]);
		if !include_lifecycle_artifacts {
			command.args(["--apply", "cfg: cfg // { spec = cfg.spec // { artifactSets = []; }; }"]);
		}
		let output = {
			let _span = crate::profiling::Span::new("exact-target-inventory-eval");
			command.arg(&target_installable).output()
		}
		.map_err(|error| NxdError::Io(format!("failed to evaluate exact target inventory: {error}")))?;
		if !output.status.success() {
			return Err(NxdError::InvalidConfig(format!(
				"exact target inventory evaluation failed for {target_installable}: {}",
				String::from_utf8_lossy(&output.stderr).trim()
			)));
		}
		serde_json::from_slice(&output.stdout).map_err(|error| {
			NxdError::InvalidConfig(format!(
				"invalid canonical exact target inventory from {target_installable}: {error}"
			))
		})
	}

	/// Load the same canonical site while retaining build outputs only for the
	/// already-resolved deployment targets.
	pub fn render_config_for_hosts(
		source: ConfigSource,
		requested_hosts: &[String],
	) -> Result<CanonicalConfig, NxdError> {
		let mut config = Self::render_config_inventory(source.clone())?;
		Self::resolve_target_outputs(&source, &mut config, requested_hosts)?;
		Ok(config)
	}

	pub fn resolve_target_outputs(
		source: &ConfigSource,
		config: &mut CanonicalConfig,
		requested_hosts: &[String],
	) -> Result<(), NxdError> {
		Self::resolve_target_outputs_with_logger(
			source,
			config,
			requested_hosts,
			&crate::Logger::silent(),
		)
	}

	pub fn resolve_target_outputs_with_logger(
		source: &ConfigSource,
		config: &mut CanonicalConfig,
		requested_hosts: &[String],
		logger: &crate::Logger,
	) -> Result<(), NxdError> {
		Self::resolve_target_outputs_with_logger_and_evaluator(
			source,
			config,
			requested_hosts,
			logger,
			|cmd| cmd.output(),
		)
	}

	pub fn resolve_target_outputs_with_logger_and_evaluator<F>(
		source: &ConfigSource,
		config: &mut CanonicalConfig,
		requested_hosts: &[String],
		logger: &crate::Logger,
		evaluator: F,
	) -> Result<(), NxdError>
	where
		F: FnOnce(&mut std::process::Command) -> std::io::Result<std::process::Output>,
	{
		if requested_hosts.is_empty() {
			return Ok(());
		}
		let buildable_hosts: Vec<String> = requested_hosts
			.iter()
			.filter(|hostname| {
				!config.spec.resources.iter().any(|resource| match resource {
					crate::contract::Resource::DeploymentTarget(target) => {
						let target_host = target.id.strip_prefix("deployment-target/").unwrap_or(&target.id);
						target_host == *hostname && !target.metadata.build_system
					}
					_ => false,
				})
			})
			.cloned()
			.collect();

		if buildable_hosts.is_empty() {
			project_target_outputs(config, &[]);
			return Ok(());
		}
		let ConfigSource::NixInstallable(installable) = source else {
			project_target_outputs(config, &buildable_hosts);
			return Ok(());
		};
		let (flake, attribute) = installable.rsplit_once('#').ok_or_else(|| {
			NxdError::InvalidConfig(
				"selected Nix output resolution requires an nxdConfigurations.<site> installable"
					.to_string(),
			)
		})?;
		let site = attribute.strip_prefix("nxdConfigurations.").ok_or_else(|| {
			NxdError::InvalidConfig(
				"selected Nix output resolution requires an nxdConfigurations.<site> installable"
					.to_string(),
			)
		})?;
		for hostname in &buildable_hosts {
			let requires_secrets = config.spec.resources.iter().any(|resource| {
				matches!(resource, crate::contract::Resource::DeploymentTarget(target)
					if target.id == format!("deployment-target/{hostname}")
						&& target.metadata.deployment.require_secrets)
			});
			if requires_secrets {
				let source = crate::config::resolve_host_sops_source(hostname).ok_or_else(|| {
					NxdError::InvalidConfig(format!(
						"deployment-target/{hostname} requires installer secrets but no host SOPS input resolves"
					))
				})?;
				if !source.path.is_file() {
					return Err(NxdError::InvalidConfig(format!(
						"deployment-target/{hostname} requires installer secrets but {} is not a file",
						source.path.display()
					)));
				}
			}
		}
		// Secret staging stays silent: it names host secret file paths, and this
		// phase's progress is reported below without them.
		let secret_store = if flake_declares_secret_input(flake) {
			crate::workspace::source::stage_hosts_installer_input(
				&buildable_hosts,
				&crate::process::Logger::silent(),
			)
			.map_err(|error| NxdError::Io(format!("failed to stage selected host secrets: {error}")))?
		} else {
			None
		};

		logger.info("evaluating selected target outputs...");
		let eval_start = std::time::Instant::now();
		let output_installable = format!("{flake}#nxdTargetOutputs.{site}");
		let resolved: BTreeMap<String, ResolvedTargetOutput> = {
			let _span = crate::profiling::Span::new("selected-target-output-eval");
			if buildable_hosts.is_empty() {
				BTreeMap::new()
			} else {
				let hosts_json = serde_json::to_string(&buildable_hosts)?;
				let hosts_literal = serde_json::to_string(&hosts_json)?;
				let apply_expression = format!(
					"let requested = builtins.fromJSON {hosts_literal}; in outputs: builtins.listToAttrs (map (name: {{ inherit name; value = outputs.${{name}} or (throw (\"missing target output \" + name)); }}) requested)"
				);
				let mut command = crate::process::sanitized_command("nix");
				command.args([
					"--extra-experimental-features",
					"nix-command flakes",
					"eval",
					"--json",
					"--impure",
					"--no-eval-cache",
					"--no-write-lock-file",
					"--apply",
					&apply_expression,
				]);
				if let Some(secret_store) = &secret_store {
					command.args([
						"--override-input",
						crate::config::SECRET_INPUT_NAME,
						&format!("path:{secret_store}"),
					]);
				}
				command.arg(&output_installable);
				let output = evaluator(&mut command).map_err(|error| {
					NxdError::Io(format!("failed to resolve selected Nix outputs: {error}"))
				})?;
				if !output.status.success() {
					return Err(NxdError::Io(format!(
						"selected Nix output evaluation failed for {output_installable}: {}",
						String::from_utf8_lossy(&output.stderr).trim()
					)));
				}
				serde_json::from_slice(&output.stdout).map_err(|error| {
					NxdError::InvalidConfig(format!("invalid selected Nix output map: {error}"))
				})?
			}
		};
		logger.info(&format!(
			"evaluated selected target outputs in {}",
			crate::progress::log::format_elapsed(eval_start.elapsed())
		));
		let needs_remote_evaluation = config.spec.resources.iter().any(|resource| {
			matches!(resource, crate::contract::Resource::DeploymentTarget(target)
				if buildable_hosts.iter().any(|hostname| target.id == format!("deployment-target/{hostname}"))
					&& !target.metadata.deployment.local_eval)
		});
		let (evaluation_source, evaluation_source_inputs, source_declares_secret_input) =
			if needs_remote_evaluation {
				logger.info("archiving evaluation source for remote targets...");
				let archive_start = std::time::Instant::now();
				let archive = crate::process::sanitized_command("nix")
					.args([
						"--extra-experimental-features",
						"nix-command flakes",
						"flake",
						"archive",
						"--json",
						"--no-write-lock-file",
						flake,
					])
					.output()
					.map_err(|error| NxdError::Io(format!("failed to archive evaluation source: {error}")))?;
				if !archive.status.success() {
					return Err(NxdError::Io(format!(
						"failed to archive evaluation source: {}",
						String::from_utf8_lossy(&archive.stderr).trim()
					)));
				}
				let archived: serde_json::Value =
					serde_json::from_slice(&archive.stdout).map_err(|error| {
						NxdError::InvalidConfig(format!("invalid archived evaluation source: {error}"))
					})?;
				let source = archived
					.get("path")
					.and_then(serde_json::Value::as_str)
					.filter(|path| path.starts_with("/nix/store/"))
					.ok_or_else(|| {
						NxdError::InvalidConfig(
							"archived evaluation source did not return a Nix store path".to_string(),
						)
					})?
					.to_string();
				let inputs = archived_input_paths(&archived)?;
				logger.info(&format!(
					"archived evaluation source in {}",
					crate::progress::log::format_elapsed(archive_start.elapsed())
				));
				(Some(source), inputs, archive_declares_secret_input(&archived))
			} else {
				(None, Vec::new(), false)
			};
		for resource in &mut config.spec.resources {
			if let crate::contract::Resource::DeploymentTarget(target) = resource {
				let hostname = target.id.strip_prefix("deployment-target/").unwrap_or(&target.id);
				if let Some(binding) = resolved.get(hostname) {
					target.metadata.system_output = binding.system_output.clone();
					target.metadata.system_derivation = binding.system_derivation.clone();
					target.metadata.disko_output = binding.disko_output.clone();
					if !target.metadata.deployment.local_eval {
						target.metadata.evaluation_source = evaluation_source.clone();
						target.metadata.evaluation_source_inputs = evaluation_source_inputs.clone();
						if source_declares_secret_input {
							target.metadata.evaluation_secret_source = secret_store.clone();
						}
					}
				}
			}
		}
		Ok(())
	}

	fn render_config_projected(
		source: ConfigSource,
		requested_hosts: Option<&[String]>,
	) -> Result<CanonicalConfig, NxdError> {
		match source {
			ConfigSource::CanonicalJson(path) => {
				let content = fs::read_to_string(&path).map_err(|error| {
					NxdError::Io(format!("failed to read config JSON {}: {error}", path.display()))
				})?;
				let mut config = parse_canonical_config(&content).map_err(|error| {
					NxdError::InvalidConfig(format!("invalid canonical config JSON: {error}"))
				})?;
				if let Some(hosts) = requested_hosts {
					project_target_outputs(&mut config, hosts);
				}
				Ok(config)
			}
			ConfigSource::NixInstallable(installable) => {
				if installable.trim().is_empty()
					|| installable.contains(char::is_control)
					|| installable.starts_with('-')
				{
					return Err(NxdError::InvalidConfig(
						"Nix installable must be a non-empty positional value".to_string(),
					));
				}
				let mut command = crate::process::sanitized_command("nix");
				command.args([
					"--extra-experimental-features",
					"nix-command flakes",
					"eval",
					"--json",
					"--impure",
					"--no-eval-cache",
					"--no-write-lock-file",
				]);
				let apply_expression;
				if let Some(hosts) = requested_hosts {
					let hosts_json = serde_json::to_string(hosts)?;
					let hosts_literal = serde_json::to_string(&hosts_json)?;
					apply_expression = format!(
						"let requested = builtins.fromJSON {hosts_literal}; in cfg: cfg // {{ spec = cfg.spec // {{ resources = map (resource: if (resource.kind or \"\") != \"deploymentTarget\" || builtins.elem (builtins.replaceStrings [\"deployment-target/\"] [\"\"] resource.id) requested then resource else resource // {{ metadata = builtins.removeAttrs resource.metadata [\"systemOutput\" \"systemDerivation\" \"diskoOutput\"]; }}) cfg.spec.resources; }}; }}"
					);
					command.args(["--apply", &apply_expression]);
				}
				let output = command
					.arg(&installable)
					.output()
					.map_err(|error| NxdError::Io(format!("failed to execute Nix evaluator: {error}")))?;
				if !output.status.success() {
					let stderr = String::from_utf8_lossy(&output.stderr);
					let stdout = String::from_utf8_lossy(&output.stdout);
					let detail = if !stderr.trim().is_empty() {
						stderr.trim().to_string()
					} else {
						stdout.trim().to_string()
					};
					return Err(NxdError::Io(format!(
						"Nix evaluator failed for {installable} with status {}: {detail}",
						output.status
					)));
				}
				serde_json::from_slice::<CanonicalConfig>(&output.stdout).map_err(|error| {
					NxdError::InvalidConfig(format!("invalid canonical Nix output: {error}"))
				})
			}
		}
	}

	pub fn plan(&self, request: PlanRequest) -> Result<PlanEnvelope, NxdError> {
		self.plan_request(request, &crate::Logger::silent())
	}

	pub fn plan_with_progress(
		&self,
		request: PlanRequest,
		logger: crate::Logger,
	) -> Result<PlanEnvelope, NxdError> {
		self.plan_request(request, &logger)
	}

	pub fn exec_plan(
		&self,
		request: PlanRequest,
		argv: Vec<String>,
	) -> Result<PlanEnvelope, NxdError> {
		self.exec_plan_with_progress(request, argv, crate::Logger::silent())
	}

	pub fn exec_plan_with_progress(
		&self,
		request: PlanRequest,
		argv: Vec<String>,
		logger: crate::Logger,
	) -> Result<PlanEnvelope, NxdError> {
		if argv.is_empty()
			|| argv.iter().any(|value| value.is_empty() || value.contains(char::is_control))
		{
			return Err(NxdError::InvalidConfig(
				"exec requires a non-empty argv vector without empty or control-character arguments"
					.to_string(),
			));
		}
		self.plan_request_with_exec(request, Some(argv), &logger)
	}

	pub fn info(&self, request: InfoRequest) -> Result<InfoReport, NxdError> {
		let config = match self.current_config() {
			Some(config) => config,
			None => Self::render_config_inventory(request.source)?,
		};
		validate_canonical_config(&config).map_err(|error| NxdError::InvalidConfig(error.0))?;
		provider_lifecycle::deployment_target_info(
			self.external_runtime(),
			&config,
			&request.target,
			request.observe_ip,
			request.wait,
		)
	}

	pub fn apply(&self, request: ApplyRequest) -> Result<ApplyReport, NxdError> {
		self.apply_request(request, &crate::Logger::silent())
	}

	pub fn apply_with_progress(
		&self,
		request: ApplyRequest,
		logger: crate::Logger,
	) -> Result<ApplyReport, NxdError> {
		self.apply_request(request, &logger)
	}

	/// Create digest-bound approval evidence for a reviewed plan (no mutation).
	pub fn create_approval(
		&self,
		request: CreateApprovalRequest,
	) -> Result<crate::host_lifecycle::ApprovalEvidence, NxdError> {
		let content = fs::read_to_string(&request.plan).map_err(|error| {
			NxdError::Io(format!("failed to read plan {}: {error}", request.plan.display()))
		})?;
		let plan = parse_plan_envelope(&content)
			.map_err(|error| NxdError::InvalidConfig(format!("invalid plan JSON: {error}")))?;
		let plan_digest = plan
			.digest()
			.map_err(|error| NxdError::InvalidConfig(format!("failed to digest plan: {error}")))?;
		let now = std::time::SystemTime::now()
			.duration_since(std::time::UNIX_EPOCH)
			.map(|duration| duration.as_secs())
			.unwrap_or(0);
		deployment_target::approval::create_approval_evidence(
			&plan,
			&plan_digest,
			&request.principal,
			now,
			request.expires_at_unix,
		)
		.map_err(NxdError::PolicyRejected)
	}

	/// Import and validate approval evidence against a plan without applying.
	pub fn validate_approval(&self, request: ValidateApprovalRequest) -> Result<(), NxdError> {
		let content = fs::read_to_string(&request.plan).map_err(|error| {
			NxdError::Io(format!("failed to read plan {}: {error}", request.plan.display()))
		})?;
		let plan = parse_plan_envelope(&content)
			.map_err(|error| NxdError::InvalidConfig(format!("invalid plan JSON: {error}")))?;
		let plan_digest = plan
			.digest()
			.map_err(|error| NxdError::InvalidConfig(format!("failed to digest plan: {error}")))?;
		let evidence = deployment_target::approval::load_approval_evidence(&request.approval_evidence)
			.map_err(NxdError::InvalidConfig)?;
		let now = std::time::SystemTime::now()
			.duration_since(std::time::UNIX_EPOCH)
			.map(|duration| duration.as_secs())
			.unwrap_or(0);
		deployment_target::approval::validate_approval_for_plan(&plan, &plan_digest, &evidence, now)
			.map_err(NxdError::PolicyRejected)
	}

	pub fn show_run(&self, run_id: Option<&str>) -> Result<serde_json::Value, NxdError> {
		self.show_run_request(run_id)
	}

	pub fn monitor_run(&self, run_id: &str) -> Result<MonitorRunReport, NxdError> {
		self.monitor_run_request(run_id)
	}

	pub fn cancel_run(&self, run_id: &str) -> Result<CancelRunReport, NxdError> {
		self.cancel_run_request(run_id)
	}

	pub fn verify(&self, request: VerifyRequest) -> Result<VerificationReport, NxdError> {
		verification::verify(self, request)
	}

	pub fn capture(&self, request: CaptureRequest) -> Result<CaptureReport, NxdError> {
		self.capture_request(request, &crate::Logger::silent())
	}

	pub fn capture_with_progress(
		&self,
		request: CaptureRequest,
		logger: crate::Logger,
	) -> Result<CaptureReport, NxdError> {
		self.capture_request(request, &logger)
	}

	pub fn artifact_build(
		&self,
		request: ArtifactBuildRequest,
	) -> Result<ArtifactBuildReport, NxdError> {
		self.artifact_build_request(request)
	}

	pub fn artifact_verify(&self, manifest: &Path) -> Result<(), NxdError> {
		self.artifact_verify_request(manifest)
	}

	pub fn show_config(&self, selectors: &[String]) -> Result<CanonicalConfig, NxdError> {
		let mut config = self
			.current_config()
			.ok_or_else(|| NxdError::InvalidConfig("show config requires canonical inventory".into()))?;
		validate_canonical_config(&config).map_err(|error| NxdError::InvalidConfig(error.0))?;
		if selectors.is_empty() {
			return Ok(config);
		}
		let selection =
			crate::domain::selection::resolve(&config, selectors).map_err(NxdError::InvalidConfig)?;
		config
			.spec
			.resources
			.retain(|resource| selection.resource_ids.contains(crate::contract::resource_id(resource)));
		config.spec.resources.sort_by(|left, right| {
			crate::contract::resource_id(left).cmp(crate::contract::resource_id(right))
		});
		Ok(config)
	}

	pub fn show_plan(&self, path: &Path) -> Result<PlanDisplay, NxdError> {
		let content = fs::read_to_string(path)
			.map_err(|error| NxdError::Io(format!("failed to read plan {}: {error}", path.display())))?;
		let plan = parse_plan_envelope(&content)
			.map_err(|error| NxdError::InvalidConfig(format!("invalid plan JSON: {error}")))?;
		let plan_digest = plan
			.digest()
			.map_err(|error| NxdError::InvalidConfig(format!("failed to digest plan: {error}")))?;
		Ok(PlanDisplay { plan, plan_digest })
	}
}

#[cfg(test)]
mod tests;

mod apply;
mod artifacts;
mod capture;
mod contracts;
mod deployment_target;
pub use contracts::*;
mod host_planes;
mod planning;
mod provider_lifecycle;
pub mod secret_mediation;
mod verification;

fn source_digest_input(source: &ConfigSource) -> Result<String, NxdError> {
	match source {
		ConfigSource::CanonicalJson(path) => fs::read_to_string(path).map_err(|error| {
			NxdError::Io(format!("failed to read config JSON {}: {error}", path.display()))
		}),
		ConfigSource::NixInstallable(installable) => Ok(format!("nix:{installable}")),
	}
}