cargo-rail 0.21.0

//! Non-circular pre-execution identities for Cargo build scripts.

use std::collections::{BTreeMap, BTreeSet};
use std::fmt;
use std::path::Path;

use serde::{Deserialize, Serialize};

use crate::compiler::observation::{CompilationProfile, CompilationRole, FileObservation, ObservationPath};
use crate::error::RailResult;
use crate::source::ContentDigest;

pub(crate) mod result;

pub(crate) use result::{
  BuildScriptCargoOutputSummary, BuildScriptResultAnalysis, BuildScriptResultInputs, analyze_result,
};

const BUILD_SCRIPT_ACTION_KEY_VERSION: u32 = 1;
const BUILD_SCRIPT_ACTION_SEMANTICS_VERSION: u32 = 1;

/// Diagnostic result of deriving one build-script action key.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub(crate) struct BuildScriptActionKeyAnalysis {
  version: u32,
  #[serde(skip_serializing_if = "Option::is_none")]
  key: Option<String>,
  source_inputs: usize,
  environment_entries: usize,
  dependency_results: usize,
  #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
  secret_capabilities: BTreeSet<String>,
  reasons: BTreeSet<String>,
}

impl BuildScriptActionKeyAnalysis {
  /// Return the authorizing pre-execution key when every input was proven.
  pub(crate) fn key(&self) -> Option<&str> {
    self.key.as_deref()
  }
}

/// Exact inputs known immediately before one build-script process starts.
///
/// The script's emitted instructions, observed reads, and generated files are
/// intentionally absent: those are result fields and cannot identify their own
/// producing action.
#[derive(Debug, Clone)]
pub(crate) struct BuildScriptActionInputs {
  pub(crate) compiled_artifact: Option<FileObservation>,
  pub(crate) source_inputs: Vec<FileObservation>,
  pub(crate) manifest_closure: Option<String>,
  pub(crate) lock_closure: Option<String>,
  pub(crate) toolchain: Option<String>,
  pub(crate) action_id: String,
  pub(crate) package: String,
  pub(crate) arguments: Vec<String>,
  pub(crate) working_directory: Option<String>,
  pub(crate) host_target: String,
  pub(crate) target: String,
  pub(crate) target_identity: Option<String>,
  pub(crate) role: CompilationRole,
  pub(crate) profile: CompilationProfile,
  pub(crate) features: BTreeSet<String>,
  pub(crate) cfg: BTreeSet<String>,
  pub(crate) configuration: Option<String>,
  /// Complete portable non-secret environment, or `None` while ambient values
  /// can still reach the process.
  pub(crate) environment: Option<BTreeMap<String, String>>,
  pub(crate) secret_environment: BTreeSet<String>,
  /// Actions that must complete before this script runs and their verified
  /// result digests. The sets must match exactly.
  pub(crate) dependency_actions: BTreeSet<String>,
  pub(crate) dependency_results: Option<BTreeMap<String, String>>,
  /// Stable logical launch layout. These remain absent until execution is
  /// isolated from ambient filesystem, process, network, clock, randomness,
  /// and persistent output-directory state.
  pub(crate) executable_path: Option<String>,
  pub(crate) output_root: Option<String>,
  pub(crate) platform_identity: Option<String>,
}

#[derive(Debug, Serialize)]
struct BuildScriptArtifactIdentity<'a> {
  content_digest: &'a str,
  executable: bool,
  symlink_target: Option<&'a str>,
}

#[derive(Serialize)]
struct BuildScriptActionKeyMaterial<'a> {
  version: u32,
  semantics_version: u32,
  compiled_artifact: BuildScriptArtifactIdentity<'a>,
  source_inputs: &'a [FileObservation],
  manifest_closure: &'a str,
  lock_closure: &'a str,
  toolchain: &'a str,
  action_id: &'a str,
  package: &'a str,
  arguments: &'a [String],
  working_directory: &'a str,
  host_target: &'a str,
  target: &'a str,
  target_identity: &'a str,
  role: CompilationRole,
  profile: &'a CompilationProfile,
  features: &'a BTreeSet<String>,
  cfg: &'a BTreeSet<String>,
  configuration: &'a str,
  environment: &'a BTreeMap<String, String>,
  dependency_results: &'a BTreeMap<String, String>,
  executable_path: &'a str,
  output_root: &'a str,
  platform_identity: &'a str,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct BuildScriptActionKey {
  version: u32,
  digest: ContentDigest,
}

impl fmt::Display for BuildScriptActionKey {
  fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    write!(formatter, "build-script-v{}-sha256-{}", self.version, self.digest)
  }
}

/// Derive an authorizing key only when every pre-execution input is complete.
pub(crate) fn analyze_action_key(
  source_root: &Path,
  mut inputs: BuildScriptActionInputs,
) -> RailResult<BuildScriptActionKeyAnalysis> {
  inputs.source_inputs.sort();
  inputs.source_inputs.dedup();

  let mut reasons = BTreeSet::new();
  if inputs.compiled_artifact.is_none() {
    reasons.insert("compiled_build_script_artifact_unavailable".to_string());
  }
  if inputs.source_inputs.is_empty() {
    reasons.insert("build_script_source_inputs_unavailable".to_string());
  }
  for input in &inputs.source_inputs {
    if matches!(input.path, ObservationPath::Host(_)) {
      reasons.insert("build_script_source_input_outside_repository".to_string());
    }
  }
  require(
    &inputs.manifest_closure,
    "build_script_manifest_closure_unavailable",
    &mut reasons,
  );
  require(
    &inputs.lock_closure,
    "build_script_lock_closure_unavailable",
    &mut reasons,
  );
  require(
    &inputs.toolchain,
    "build_script_toolchain_identity_unavailable",
    &mut reasons,
  );
  require(
    &inputs.working_directory,
    "build_script_working_directory_unavailable",
    &mut reasons,
  );
  require(
    &inputs.target_identity,
    "build_script_target_identity_unavailable",
    &mut reasons,
  );
  require(
    &inputs.configuration,
    "build_script_configuration_identity_unavailable",
    &mut reasons,
  );
  if inputs.role != CompilationRole::Host {
    reasons.insert("build_script_host_role_unproven".to_string());
  }
  if inputs.action_id.is_empty() {
    reasons.insert("build_script_action_identity_unavailable".to_string());
  }
  if inputs.package.is_empty() {
    reasons.insert("build_script_package_identity_unavailable".to_string());
  }
  if inputs.host_target.is_empty() || inputs.target.is_empty() {
    reasons.insert("build_script_platform_role_unavailable".to_string());
  }

  if !inputs.secret_environment.is_empty() {
    reasons.insert("secret_build_script_environment".to_string());
  }
  let environment_entries = inputs.environment.as_ref().map_or(0, BTreeMap::len);
  if inputs.environment.is_none() {
    reasons.insert("build_script_environment_uncontrolled".to_string());
  }
  let dependency_result_count = inputs.dependency_results.as_ref().map_or(0, BTreeMap::len);
  match &inputs.dependency_results {
    Some(results)
      if results
        .keys()
        .map(String::as_str)
        .eq(inputs.dependency_actions.iter().map(String::as_str)) => {}
    Some(_) => {
      reasons.insert("build_script_dependency_result_set_incomplete".to_string());
    }
    None => {
      reasons.insert("build_script_dependency_results_unavailable".to_string());
    }
  }
  if inputs.dependency_actions.contains(&inputs.action_id) {
    reasons.insert("build_script_result_cycle".to_string());
  }
  if [
    inputs.executable_path.as_deref(),
    inputs.output_root.as_deref(),
    inputs.platform_identity.as_deref(),
  ]
  .into_iter()
  .any(|value| value.is_none_or(str::is_empty))
  {
    reasons.insert("build_script_ambient_inputs_unobserved".to_string());
  }
  if inputs
    .working_directory
    .as_deref()
    .is_some_and(|path| !path.starts_with("repository:"))
    || inputs
      .executable_path
      .as_deref()
      .is_some_and(|path| !path.starts_with("execution:"))
    || inputs
      .output_root
      .as_deref()
      .is_some_and(|path| !path.starts_with("output:"))
  {
    reasons.insert("build_script_logical_layout_invalid".to_string());
  }
  if inputs
    .environment
    .as_ref()
    .is_some_and(|environment| environment.keys().any(String::is_empty))
  {
    reasons.insert("build_script_environment_name_invalid".to_string());
  }
  if inputs.dependency_actions.iter().any(String::is_empty)
    || inputs.dependency_results.as_ref().is_some_and(|results| {
      results
        .iter()
        .any(|(action, result)| action.is_empty() || result.is_empty())
    })
  {
    reasons.insert("build_script_dependency_result_invalid".to_string());
  }

  if reasons.is_empty() {
    if inputs
      .compiled_artifact
      .as_ref()
      .is_some_and(|artifact| !artifact.revalidate(source_root))
    {
      reasons.insert("compiled_build_script_artifact_changed".to_string());
    }
    if inputs.source_inputs.iter().any(|input| !input.revalidate(source_root)) {
      reasons.insert("build_script_source_input_changed".to_string());
    }
    if contains_physical_source_root(&inputs, source_root) {
      reasons.insert("physical_checkout_path_in_build_script_key".to_string());
    }
  }

  let key = if reasons.is_empty()
    && let Some(material) = key_material(&inputs)
  {
    let mut bytes = Vec::from(&b"cargo-rail-build-script-action-key\0"[..]);
    bytes.extend(serde_json::to_vec(&material)?);
    Some(BuildScriptActionKey {
      version: BUILD_SCRIPT_ACTION_KEY_VERSION,
      digest: ContentDigest::sha256(&bytes),
    })
  } else {
    None
  }
  .map(|key| key.to_string());
  if reasons.is_empty() && key.is_none() {
    reasons.insert("build_script_pre_execution_inputs_incomplete".to_string());
  }

  Ok(BuildScriptActionKeyAnalysis {
    version: BUILD_SCRIPT_ACTION_KEY_VERSION,
    key,
    source_inputs: inputs.source_inputs.len(),
    environment_entries,
    dependency_results: dependency_result_count,
    secret_capabilities: inputs.secret_environment,
    reasons,
  })
}

fn require(value: &Option<String>, reason: &'static str, reasons: &mut BTreeSet<String>) {
  if value.as_deref().is_none_or(str::is_empty) {
    reasons.insert(reason.to_string());
  }
}

fn key_material(inputs: &BuildScriptActionInputs) -> Option<BuildScriptActionKeyMaterial<'_>> {
  let compiled_artifact = inputs.compiled_artifact.as_ref()?;
  Some(BuildScriptActionKeyMaterial {
    version: BUILD_SCRIPT_ACTION_KEY_VERSION,
    semantics_version: BUILD_SCRIPT_ACTION_SEMANTICS_VERSION,
    compiled_artifact: BuildScriptArtifactIdentity {
      content_digest: &compiled_artifact.content_digest,
      executable: compiled_artifact.executable,
      symlink_target: compiled_artifact.symlink_target.as_deref(),
    },
    source_inputs: &inputs.source_inputs,
    manifest_closure: inputs.manifest_closure.as_deref()?,
    lock_closure: inputs.lock_closure.as_deref()?,
    toolchain: inputs.toolchain.as_deref()?,
    action_id: &inputs.action_id,
    package: &inputs.package,
    arguments: &inputs.arguments,
    working_directory: inputs.working_directory.as_deref()?,
    host_target: &inputs.host_target,
    target: &inputs.target,
    target_identity: inputs.target_identity.as_deref()?,
    role: inputs.role,
    profile: &inputs.profile,
    features: &inputs.features,
    cfg: &inputs.cfg,
    configuration: inputs.configuration.as_deref()?,
    environment: inputs.environment.as_ref()?,
    dependency_results: inputs.dependency_results.as_ref()?,
    executable_path: inputs.executable_path.as_deref()?,
    output_root: inputs.output_root.as_deref()?,
    platform_identity: inputs.platform_identity.as_deref()?,
  })
}

fn contains_physical_source_root(inputs: &BuildScriptActionInputs, source_root: &Path) -> bool {
  let roots = physical_source_roots(source_root);
  let contains_root = |value: &str| roots.iter().any(|root| value.contains(root));
  inputs.arguments.iter().any(|value| contains_root(value))
    || inputs.working_directory.as_deref().is_some_and(contains_root)
    || contains_root(&inputs.host_target)
    || contains_root(&inputs.target)
    || inputs.target_identity.as_deref().is_some_and(contains_root)
    || inputs.environment.as_ref().is_some_and(|environment| {
      environment
        .iter()
        .any(|(name, value)| contains_root(name) || contains_root(value))
    })
    || inputs.dependency_actions.iter().any(|action| contains_root(action))
    || inputs.dependency_results.as_ref().is_some_and(|results| {
      results
        .iter()
        .any(|(action, result)| contains_root(action) || contains_root(result))
    })
    || [
      inputs.manifest_closure.as_deref(),
      inputs.lock_closure.as_deref(),
      inputs.toolchain.as_deref(),
      Some(inputs.action_id.as_str()),
      Some(inputs.package.as_str()),
      inputs.configuration.as_deref(),
      inputs.executable_path.as_deref(),
      inputs.output_root.as_deref(),
      inputs.platform_identity.as_deref(),
      inputs
        .compiled_artifact
        .as_ref()
        .and_then(|artifact| artifact.symlink_target.as_deref()),
    ]
    .into_iter()
    .flatten()
    .any(contains_root)
    || inputs
      .source_inputs
      .iter()
      .filter_map(|input| input.symlink_target.as_deref())
      .any(contains_root)
}

fn physical_source_roots(source_root: &Path) -> Vec<String> {
  let mut roots = vec![
    source_root.to_string_lossy().into_owned(),
    crate::utils::path_to_git_format(source_root),
  ];
  if let Ok(canonical) = std::fs::canonicalize(source_root) {
    roots.push(canonical.to_string_lossy().into_owned());
    roots.push(crate::utils::path_to_git_format(&canonical));
  }
  roots.sort();
  roots.dedup();
  roots.retain(|root| !root.is_empty());
  roots
}

#[cfg(test)]
mod tests {
  use std::fs;

  use tempfile::TempDir;

  use super::*;

  fn observation(root: &Path, relative: &str, bytes: &[u8]) -> FileObservation {
    let path = root.join(relative);
    if let Some(parent) = path.parent() {
      fs::create_dir_all(parent).expect("create observation parent");
    }
    fs::write(&path, bytes).expect("write observation file");
    FileObservation::capture(&path, root, root).expect("capture observation")
  }

  fn complete_inputs(root: &Path) -> BuildScriptActionInputs {
    BuildScriptActionInputs {
      compiled_artifact: Some(observation(root, "target/build-script", b"program")),
      source_inputs: vec![observation(root, "crates/example/build.rs", b"fn main() {}")],
      manifest_closure: Some("sha256:manifest".to_string()),
      lock_closure: Some("sha256:lock".to_string()),
      toolchain: Some("sha256:toolchain".to_string()),
      action_id: "build-script:example".to_string(),
      package: "local:crates/example/Cargo.toml#example@0.1.0".to_string(),
      arguments: Vec::new(),
      working_directory: Some("repository:crates/example".to_string()),
      host_target: "aarch64-apple-darwin".to_string(),
      target: "x86_64-unknown-linux-gnu".to_string(),
      target_identity: Some("sha256:target".to_string()),
      role: CompilationRole::Host,
      profile: CompilationProfile {
        opt_level: "0".to_string(),
        debuginfo: "2".to_string(),
        debug_assertions: true,
        overflow_checks: true,
        test: false,
      },
      features: BTreeSet::from(["native".to_string()]),
      cfg: BTreeSet::from(["target_os=linux".to_string()]),
      configuration: Some("sha256:configuration".to_string()),
      environment: Some(BTreeMap::from([
        (
          "CARGO_MANIFEST_DIR".to_string(),
          "repository:crates/example".to_string(),
        ),
        ("OUT_DIR".to_string(), "output:out".to_string()),
      ])),
      secret_environment: BTreeSet::new(),
      dependency_actions: BTreeSet::from(["compile:build-dependency".to_string()]),
      dependency_results: Some(BTreeMap::from([(
        "compile:build-dependency".to_string(),
        "v1-sha256-dependency".to_string(),
      )])),
      executable_path: Some("execution:build-script".to_string()),
      output_root: Some("output:out".to_string()),
      platform_identity: Some("sha256:platform".to_string()),
    }
  }

  fn key(root: &Path, inputs: BuildScriptActionInputs) -> Option<String> {
    analyze_action_key(root, inputs).expect("analyze build-script key").key
  }

  #[test]
  fn build_script_action_key_changes_for_every_pre_execution_domain() {
    type Mutation = Box<dyn Fn(&mut BuildScriptActionInputs)>;

    let root = TempDir::new().expect("temporary source root");
    let inputs = complete_inputs(root.path());
    let baseline = key(root.path(), inputs.clone()).expect("complete inputs issue a key");
    assert!(baseline.starts_with("build-script-v1-sha256-"));
    let mutations: Vec<(&str, Mutation)> = vec![
      (
        "artifact",
        Box::new(|inputs| inputs.compiled_artifact.as_mut().unwrap().content_digest.push('0')),
      ),
      (
        "source",
        Box::new(|inputs| inputs.source_inputs[0].content_digest.push('0')),
      ),
      (
        "manifests",
        Box::new(|inputs| inputs.manifest_closure.as_mut().unwrap().push('0')),
      ),
      (
        "lock",
        Box::new(|inputs| inputs.lock_closure.as_mut().unwrap().push('0')),
      ),
      (
        "toolchain",
        Box::new(|inputs| inputs.toolchain.as_mut().unwrap().push('0')),
      ),
      ("action id", Box::new(|inputs| inputs.action_id.push('0'))),
      ("package", Box::new(|inputs| inputs.package.push('0'))),
      ("argv", Box::new(|inputs| inputs.arguments.push("--probe".to_string()))),
      (
        "working directory",
        Box::new(|inputs| inputs.working_directory.as_mut().unwrap().push('0')),
      ),
      ("host", Box::new(|inputs| inputs.host_target.push('0'))),
      ("target", Box::new(|inputs| inputs.target.push('0'))),
      (
        "target identity",
        Box::new(|inputs| inputs.target_identity.as_mut().unwrap().push('0')),
      ),
      ("role", Box::new(|inputs| inputs.role = CompilationRole::Target)),
      ("profile", Box::new(|inputs| inputs.profile.opt_level.push('1'))),
      (
        "features",
        Box::new(|inputs| {
          inputs.features.insert("simd".to_string());
        }),
      ),
      (
        "cfg",
        Box::new(|inputs| {
          inputs.cfg.insert("target_env=gnu".to_string());
        }),
      ),
      (
        "configuration",
        Box::new(|inputs| inputs.configuration.as_mut().unwrap().push('0')),
      ),
      (
        "environment",
        Box::new(|inputs| {
          let values = inputs.environment.as_mut().unwrap();
          values.insert("CC".to_string(), "literal:clang".to_string());
        }),
      ),
      (
        "dependency result",
        Box::new(|inputs| {
          let results = inputs.dependency_results.as_mut().unwrap();
          results.get_mut("compile:build-dependency").unwrap().push('0');
        }),
      ),
      (
        "dependency action",
        Box::new(|inputs| {
          let result = inputs
            .dependency_results
            .as_mut()
            .unwrap()
            .remove("compile:build-dependency")
            .unwrap();
          inputs.dependency_actions.remove("compile:build-dependency");
          inputs
            .dependency_actions
            .insert("compile:other-build-dependency".to_string());
          inputs
            .dependency_results
            .as_mut()
            .unwrap()
            .insert("compile:other-build-dependency".to_string(), result);
        }),
      ),
      (
        "executable path",
        Box::new(|inputs| inputs.executable_path.as_mut().unwrap().push('0')),
      ),
      (
        "output root",
        Box::new(|inputs| {
          inputs.output_root.as_mut().unwrap().push('0');
        }),
      ),
      (
        "platform identity",
        Box::new(|inputs| inputs.platform_identity.as_mut().unwrap().push('0')),
      ),
    ];

    for (name, mutate) in mutations {
      let mut changed = inputs.clone();
      mutate(&mut changed);
      assert_ne!(
        key(root.path(), changed).as_deref(),
        Some(baseline.as_str()),
        "{name} collided"
      );
    }
  }

  #[test]
  fn build_script_action_key_is_checkout_root_independent() {
    let left = TempDir::new().expect("left source root");
    let right = TempDir::new().expect("right source root");
    let left_key = key(left.path(), complete_inputs(left.path()));
    let right_key = key(right.path(), complete_inputs(right.path()));
    assert_eq!(left_key, right_key);
  }

  #[test]
  fn build_script_action_key_rejects_physical_checkout_paths() {
    let root = TempDir::new().expect("temporary source root");
    let mut inputs = complete_inputs(root.path());
    inputs
      .environment
      .as_mut()
      .unwrap()
      .insert("LEAKED_ROOT".to_string(), root.path().to_string_lossy().into_owned());

    let analysis = analyze_action_key(root.path(), inputs).expect("analyze physical checkout path");
    assert!(analysis.key.is_none());
    assert!(analysis.reasons.contains("physical_checkout_path_in_build_script_key"));
  }

  #[test]
  fn build_script_action_key_changes_after_recapturing_exact_bytes() {
    let artifact_root = TempDir::new().expect("artifact source root");
    let mut artifact_inputs = complete_inputs(artifact_root.path());
    let artifact_baseline = key(artifact_root.path(), artifact_inputs.clone()).expect("artifact baseline key");
    fs::write(artifact_root.path().join("target/build-script"), b"PROGRAM").expect("same-size artifact mutation");
    artifact_inputs.compiled_artifact = Some(
      FileObservation::capture(
        &artifact_root.path().join("target/build-script"),
        artifact_root.path(),
        artifact_root.path(),
      )
      .expect("recapture artifact"),
    );
    assert_ne!(
      key(artifact_root.path(), artifact_inputs).as_deref(),
      Some(artifact_baseline.as_str())
    );

    let source_root = TempDir::new().expect("source input root");
    let mut source_inputs = complete_inputs(source_root.path());
    let source_baseline = key(source_root.path(), source_inputs.clone()).expect("source baseline key");
    fs::write(source_root.path().join("crates/example/build.rs"), b"fn main(){ }").expect("same-size source mutation");
    source_inputs.source_inputs[0] = FileObservation::capture(
      &source_root.path().join("crates/example/build.rs"),
      source_root.path(),
      source_root.path(),
    )
    .expect("recapture source");
    assert_ne!(
      key(source_root.path(), source_inputs).as_deref(),
      Some(source_baseline.as_str())
    );
  }

  #[test]
  fn build_script_action_key_refuses_ambient_or_future_dependent_authority() {
    let root = TempDir::new().expect("temporary source root");
    let mut inputs = complete_inputs(root.path());
    inputs.environment = None;
    inputs.dependency_results = None;
    inputs.executable_path = None;
    inputs.output_root = None;
    inputs.platform_identity = None;

    let analysis = analyze_action_key(root.path(), inputs).expect("analyze incomplete key");
    assert!(analysis.key.is_none());
    assert_eq!(
      analysis.reasons.iter().map(String::as_str).collect::<Vec<_>>(),
      vec![
        "build_script_ambient_inputs_unobserved",
        "build_script_dependency_results_unavailable",
        "build_script_environment_uncontrolled",
      ]
    );
  }

  #[test]
  fn build_script_action_key_requires_every_static_input() {
    type MissingInput = Box<dyn Fn(&mut BuildScriptActionInputs)>;

    let root = TempDir::new().expect("temporary source root");
    let cases: Vec<(&str, &str, MissingInput)> = vec![
      (
        "artifact",
        "compiled_build_script_artifact_unavailable",
        Box::new(|inputs| inputs.compiled_artifact = None),
      ),
      (
        "source",
        "build_script_source_inputs_unavailable",
        Box::new(|inputs| inputs.source_inputs.clear()),
      ),
      (
        "manifests",
        "build_script_manifest_closure_unavailable",
        Box::new(|inputs| inputs.manifest_closure = None),
      ),
      (
        "lock",
        "build_script_lock_closure_unavailable",
        Box::new(|inputs| inputs.lock_closure = None),
      ),
      (
        "toolchain",
        "build_script_toolchain_identity_unavailable",
        Box::new(|inputs| inputs.toolchain = None),
      ),
      (
        "action identity",
        "build_script_action_identity_unavailable",
        Box::new(|inputs| inputs.action_id.clear()),
      ),
      (
        "working directory",
        "build_script_working_directory_unavailable",
        Box::new(|inputs| inputs.working_directory = None),
      ),
      (
        "target",
        "build_script_target_identity_unavailable",
        Box::new(|inputs| inputs.target_identity = None),
      ),
      (
        "configuration",
        "build_script_configuration_identity_unavailable",
        Box::new(|inputs| inputs.configuration = None),
      ),
    ];

    for (name, reason, remove) in cases {
      let mut inputs = complete_inputs(root.path());
      remove(&mut inputs);
      let analysis = analyze_action_key(root.path(), inputs).expect("analyze missing input");
      assert!(analysis.key.is_none(), "{name} absence issued a key");
      assert!(
        analysis.reasons.contains(reason),
        "{name} absence did not report {reason}"
      );
    }
  }

  #[test]
  fn build_script_key_analysis_never_persists_environment_values() {
    let root = TempDir::new().expect("temporary source root");
    let mut controlled = complete_inputs(root.path());
    controlled
      .environment
      .as_mut()
      .expect("controlled environment")
      .insert("VISIBLE_INPUT".to_string(), "never-persist-this-value".to_string());
    let encoded =
      serde_json::to_string(&analyze_action_key(root.path(), controlled).expect("analyze controlled environment"))
        .expect("serialize key analysis");
    assert!(!encoded.contains("never-persist-this-value"));

    let mut inputs = complete_inputs(root.path());
    inputs.secret_environment.insert("REGISTRY_TOKEN".to_string());

    let analysis = analyze_action_key(root.path(), inputs).expect("analyze secret capability");
    assert!(analysis.key.is_none());
    assert_eq!(
      analysis.secret_capabilities,
      BTreeSet::from(["REGISTRY_TOKEN".to_string()])
    );
    assert!(analysis.reasons.contains("secret_build_script_environment"));
  }

  #[test]
  fn build_script_action_key_rejects_missing_or_circular_dependency_results() {
    let root = TempDir::new().expect("temporary source root");
    let mut incomplete = complete_inputs(root.path());
    incomplete.dependency_results.as_mut().unwrap().clear();
    let analysis = analyze_action_key(root.path(), incomplete).expect("analyze incomplete dependency results");
    assert!(analysis.key.is_none());
    assert!(
      analysis
        .reasons
        .contains("build_script_dependency_result_set_incomplete")
    );

    let mut circular = complete_inputs(root.path());
    circular.dependency_actions.insert(circular.action_id.clone());
    circular
      .dependency_results
      .as_mut()
      .unwrap()
      .insert(circular.action_id.clone(), "v1-sha256-future-result".to_string());
    let analysis = analyze_action_key(root.path(), circular).expect("analyze circular dependency result");
    assert!(analysis.key.is_none());
    assert!(analysis.reasons.contains("build_script_result_cycle"));
  }

  #[test]
  fn build_script_action_key_revalidates_exact_bytes() {
    let root = TempDir::new().expect("temporary source root");
    let inputs = complete_inputs(root.path());
    fs::write(root.path().join("crates/example/build.rs"), b"fn main(){ }").expect("same-size source mutation");

    let analysis = analyze_action_key(root.path(), inputs).expect("analyze changed source");
    assert!(analysis.key.is_none());
    assert!(analysis.reasons.contains("build_script_source_input_changed"));
  }
}