luaskills 0.5.3

use semver::Version;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::{HashMap, VecDeque};
use std::env;
use std::fs::{self, File, OpenOptions};
use std::path::{Component, Path, PathBuf};
use std::process::Command;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Condvar, Mutex, OnceLock, Weak};
use std::thread;
use std::time::Duration;

use crate::runtime::managed_package::{
    ManagedFilesystemObjectIdentity, ManagedRuntimePackageContext,
    capture_managed_directory_identity, validate_managed_directory_identity,
};
use crate::runtime::path::{
    host_process_path_argument, normalize_host_input_path_text, render_host_visible_path,
};
use crate::skill::dependencies::{
    NodeRuntimeDependencySpec, NodeRuntimePackageManager, PythonRuntimeDependencySpec,
    PythonRuntimePackageManager,
};

/// Schema version used by managed runtime environment markers.
/// 受管运行时环境标记文件使用的 schema 版本。
pub const MANAGED_RUNTIME_ENV_MARKER_SCHEMA_VERSION: u32 = 2;

/// Stable reason code returned when persistent sessions are queried on Windows ARM.
/// 在 Windows ARM 上查询持久会话能力时返回的稳定原因码。
pub const WINDOWS_ARM_PERSISTENT_SESSION_UNSUPPORTED_REASON: &str = "windows_arm_is_not_supported";

/// Stable origin of one managed runtime root selected by the host boundary.
/// 宿主边界所选择单个受管运行时根的稳定来源。
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ManagedRuntimeRootSource {
    /// Root explicitly injected by the host during engine creation.
    /// 引擎创建期间由宿主显式注入的根。
    HostConfigured,
    /// Root derived from the compatible fixed layout under `runtime_root`.
    /// 从 `runtime_root` 下兼容固定布局派生的根。
    RuntimeRootDefault,
}

impl ManagedRuntimeRootSource {
    /// Return the stable machine-readable source identifier used in diagnostics and FFI payloads.
    /// 返回诊断信息与 FFI 载荷使用的稳定机器可读来源标识。
    pub fn as_str(self) -> &'static str {
        match self {
            Self::HostConfigured => "host_configured",
            Self::RuntimeRootDefault => "runtime_root_default",
        }
    }
}

/// Immutable validated roots used by managed Python and Node resolution.
/// 受管 Python 与 Node 解析使用的不可变已校验根集合。
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ManagedRuntimeRoots {
    /// Canonical LuaSkills data root retained for compatibility-owned resources.
    /// 为兼容资源保留的规范 LuaSkills 数据根。
    runtime_root: PathBuf,
    /// Canonical read-only distribution root containing `python` and `node`.
    /// 包含 `python` 与 `node` 的规范只读发行根。
    distribution_root: PathBuf,
    /// Canonical writable root containing reusable Python and Node environments.
    /// 包含可复用 Python 与 Node 环境的规范可写根。
    environment_root: PathBuf,
    /// Native identity of the runtime data root captured during construction.
    /// 构造期间捕获的运行时数据根原生身份。
    runtime_root_identity: ManagedFilesystemObjectIdentity,
    /// Native identity of an existing distribution root, mandatory for explicit roots.
    /// 已存在发行根的原生身份；显式根必须具备该身份。
    distribution_root_identity: OnceLock<ManagedFilesystemObjectIdentity>,
    /// Native identity of the safely created environment root.
    /// 安全创建后的环境根原生身份。
    environment_root_identity: Option<ManagedFilesystemObjectIdentity>,
    /// Stable source of the selected distribution root.
    /// 所选发行根的稳定来源。
    distribution_source: ManagedRuntimeRootSource,
    /// Stable source of the selected environment root.
    /// 所选环境根的稳定来源。
    environment_source: ManagedRuntimeRootSource,
}

impl ManagedRuntimeRoots {
    /// Resolve, validate, and identity-pin all managed runtime roots.
    /// 解析、校验并固定全部受管运行时根的身份。
    ///
    /// `runtime_root` is the LuaSkills data root; explicit distribution and environment roots take
    /// precedence over compatible paths derived below it. The environment root is safely created.
    /// `runtime_root` 是 LuaSkills 数据根；显式发行根和环境根优先于其下派生的兼容路径，环境根会被安全创建。
    ///
    /// Returns an immutable root set or an explicit absolute-path, type, creation, or identity error.
    /// 返回不可变根集合，或显式绝对路径、类型、创建及身份错误。
    pub fn new(
        runtime_root: &Path,
        distribution_root: Option<&Path>,
        environment_root: Option<&Path>,
    ) -> Result<Self, String> {
        // CanonicalRuntimeRoot is the authoritative data root and must already exist.
        // CanonicalRuntimeRoot 是权威数据根且必须已存在。
        let canonical_runtime_root =
            canonicalize_managed_runtime_directory(runtime_root, "runtime_root", false)?;
        // DistributionSource records whether the host overrode the compatible fixed layout.
        // DistributionSource 记录宿主是否覆盖兼容固定布局。
        let distribution_source = if distribution_root.is_some() {
            ManagedRuntimeRootSource::HostConfigured
        } else {
            ManagedRuntimeRootSource::RuntimeRootDefault
        };
        // DistributionCandidate is never resolved from environment variables or PATH.
        // DistributionCandidate 绝不会从环境变量或 PATH 解析。
        let distribution_candidate = distribution_root
            .map(Path::to_path_buf)
            .unwrap_or_else(|| canonical_runtime_root.join("dependencies").join("runtimes"));
        if !distribution_candidate.is_absolute() {
            return Err(format!(
                "managed runtime distribution source={}: managed_runtime_distribution_root must be an absolute path",
                distribution_source.as_str()
            ));
        }
        // Explicit distributions are required immediately; the compatible default remains lazy so
        // engines without managed runtime declarations preserve their existing startup behavior.
        // 显式发行根必须立即存在；兼容默认根保持延迟，以保留未声明受管运行时的引擎启动行为。
        let (canonical_distribution_root, distribution_root_identity) = match fs::canonicalize(
            &distribution_candidate,
        ) {
            Ok(path) => {
                ensure_managed_runtime_directory(&path, "managed runtime distribution root")
                    .map_err(|error| {
                        format!(
                            "managed runtime distribution source={}: {error}",
                            distribution_source.as_str()
                        )
                    })?;
                let identity =
                    capture_managed_directory_identity(&path, "managed runtime distribution root")
                        .map_err(|error| {
                            format!(
                                "managed runtime distribution source={}: {error}",
                                distribution_source.as_str()
                            )
                        })?;
                (path, Some(identity))
            }
            Err(error)
                if distribution_source == ManagedRuntimeRootSource::RuntimeRootDefault
                    && error.kind() == std::io::ErrorKind::NotFound =>
            {
                (distribution_candidate, None)
            }
            Err(error) => {
                return Err(format!(
                    "managed runtime distribution source={}: failed to canonicalize managed runtime distribution root {}: {error}",
                    distribution_source.as_str(),
                    render_host_visible_path(&distribution_candidate)
                ));
            }
        };
        // EnvironmentSource records whether the writable location was explicitly selected.
        // EnvironmentSource 记录可写位置是否由宿主显式选择。
        let environment_source = if environment_root.is_some() {
            ManagedRuntimeRootSource::HostConfigured
        } else {
            ManagedRuntimeRootSource::RuntimeRootDefault
        };
        // EnvironmentCandidate defaults to the legacy dependencies/envs layout.
        // EnvironmentCandidate 默认使用旧有 dependencies/envs 布局。
        let environment_candidate = environment_root
            .map(Path::to_path_buf)
            .unwrap_or_else(|| canonical_runtime_root.join("dependencies").join("envs"));
        if !environment_candidate.is_absolute() {
            return Err(format!(
                "managed runtime environment source={}: managed_runtime_environment_root must be an absolute path",
                environment_source.as_str()
            ));
        }
        // PlatformCapability is checked before any writable environment path is created.
        // PlatformCapability 在创建任何可写环境路径前完成检查。
        let platform_capability = current_managed_runtime_persistent_session_capability();
        let (canonical_environment_root, environment_root_identity) = if platform_capability
            .supported
        {
            let canonical = canonicalize_managed_runtime_directory(
                &environment_candidate,
                "managed runtime environment root",
                true,
            )
            .map_err(|error| {
                format!(
                    "managed runtime environment source={}: {error}",
                    environment_source.as_str()
                )
            })?;
            let identity =
                capture_managed_directory_identity(&canonical, "managed runtime environment root")
                    .map_err(|error| {
                        format!(
                            "managed runtime environment source={}: {error}",
                            environment_source.as_str()
                        )
                    })?;
            (canonical, Some(identity))
        } else {
            // UnsupportedEnvironmentRoot is never created; an existing directory may still be
            // canonicalized read-only so engine configuration remains deterministic.
            // UnsupportedEnvironmentRoot 绝不会被创建；现有目录仍可只读规范化，以保持引擎
            // 配置确定性。
            match fs::canonicalize(&environment_candidate) {
                Ok(canonical) => {
                    ensure_managed_runtime_directory(
                        &canonical,
                        "managed runtime environment root",
                    )
                    .map_err(|error| {
                        format!(
                            "managed runtime environment source={}: {error}",
                            environment_source.as_str()
                        )
                    })?;
                    let identity = capture_managed_directory_identity(
                        &canonical,
                        "managed runtime environment root",
                    )
                    .map_err(|error| {
                        format!(
                            "managed runtime environment source={}: {error}",
                            environment_source.as_str()
                        )
                    })?;
                    (canonical, Some(identity))
                }
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
                    (environment_candidate, None)
                }
                Err(error) => {
                    return Err(format!(
                        "managed runtime environment source={}: failed to canonicalize managed runtime environment root {}: {error}",
                        environment_source.as_str(),
                        render_host_visible_path(&environment_candidate)
                    ));
                }
            }
        };
        // DistributionIdentityCell supports the compatible lazy default while pinning its first
        // observed real directory object for the remainder of the root-set lifetime.
        // DistributionIdentityCell 支持兼容的延迟默认目录，并在首次观察到真实目录对象后固定其
        // 余下根集合生命周期身份。
        let distribution_identity_cell = OnceLock::new();
        if let Some(identity) = distribution_root_identity {
            distribution_identity_cell.set(identity).map_err(|_| {
                "managed runtime distribution root identity was set twice".to_string()
            })?;
        }
        Ok(Self {
            runtime_root_identity: capture_managed_directory_identity(
                &canonical_runtime_root,
                "runtime_root",
            )?,
            distribution_root_identity: distribution_identity_cell,
            environment_root_identity,
            runtime_root: canonical_runtime_root,
            distribution_root: canonical_distribution_root,
            environment_root: canonical_environment_root,
            distribution_source,
            environment_source,
        })
    }

    /// Return the canonical LuaSkills data root.
    /// 返回规范 LuaSkills 数据根。
    pub fn runtime_root(&self) -> &Path {
        &self.runtime_root
    }

    /// Return the canonical managed runtime distribution root.
    /// 返回规范受管运行时发行根。
    pub fn distribution_root(&self) -> &Path {
        &self.distribution_root
    }

    /// Return the canonical managed environment root.
    /// 返回规范受管环境根。
    pub fn environment_root(&self) -> &Path {
        &self.environment_root
    }

    /// Return the stable source of the distribution root.
    /// 返回发行根的稳定来源。
    pub fn distribution_source(&self) -> ManagedRuntimeRootSource {
        self.distribution_source
    }

    /// Return the stable source of the environment root.
    /// 返回环境根的稳定来源。
    pub fn environment_source(&self) -> ManagedRuntimeRootSource {
        self.environment_source
    }

    /// Revalidate every root whose identity is fixed for this engine or package lifetime.
    /// 重新校验当前引擎或包生命周期内固定身份的每个根。
    pub(crate) fn validate_live_filesystem_identity(&self) -> Result<(), String> {
        validate_managed_directory_identity(
            &self.runtime_root,
            &self.runtime_root_identity,
            "runtime_root",
        )?;
        if let Some(identity) = self.distribution_root_identity.get() {
            validate_managed_directory_identity(
                &self.distribution_root,
                identity,
                "managed runtime distribution root",
            )
            .map_err(|error| {
                format!(
                    "managed runtime distribution source={}: {error}",
                    self.distribution_source.as_str()
                )
            })?;
        } else {
            // MissingDefault remains valid until a package first declares a managed runtime.
            // MissingDefault 在包首次声明受管运行时前保持合法。
            let current = match fs::canonicalize(&self.distribution_root) {
                Ok(current) => Some(current),
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
                Err(error) => {
                    return Err(format!(
                        "managed runtime distribution source={}: failed to resolve managed runtime distribution root {}: {error}",
                        self.distribution_source.as_str(),
                        render_host_visible_path(&self.distribution_root)
                    ));
                }
            };
            if let Some(current) = current {
                if current != self.distribution_root {
                    return Err(format!(
                        "managed runtime distribution source={}: managed runtime distribution root changed identity: expected {}, got {}",
                        self.distribution_source.as_str(),
                        render_host_visible_path(&self.distribution_root),
                        render_host_visible_path(&current)
                    ));
                }
                ensure_managed_runtime_directory(&current, "managed runtime distribution root")
                    .map_err(|error| {
                        format!(
                            "managed runtime distribution source={}: {error}",
                            self.distribution_source.as_str()
                        )
                    })?;
                // FirstIdentity is captured only after the canonical directory and type are confirmed.
                // FirstIdentity 仅在规范目录及其类型确认后捕获。
                let first_identity = capture_managed_directory_identity(
                    &current,
                    "managed runtime distribution root",
                )
                .map_err(|error| {
                    format!(
                        "managed runtime distribution source={}: {error}",
                        self.distribution_source.as_str()
                    )
                })?;
                let _ = self.distribution_root_identity.set(first_identity);
                let expected_identity = self.distribution_root_identity.get().ok_or_else(|| {
                    format!(
                        "managed runtime distribution source={}: managed runtime distribution root identity is unavailable",
                        self.distribution_source.as_str()
                    )
                })?;
                validate_managed_directory_identity(
                    &self.distribution_root,
                    expected_identity,
                    "managed runtime distribution root",
                )
                .map_err(|error| {
                    format!(
                        "managed runtime distribution source={}: {error}",
                        self.distribution_source.as_str()
                    )
                })?;
            }
        }
        match self.environment_root_identity.as_ref() {
            Some(identity) => validate_managed_directory_identity(
                &self.environment_root,
                identity,
                "managed runtime environment root",
            )
            .map_err(|error| {
                format!(
                    "managed runtime environment source={}: {error}",
                    self.environment_source.as_str()
                )
            }),
            None if !current_managed_runtime_persistent_session_capability().supported => Ok(()),
            None => Err(format!(
                "managed runtime environment source={}: managed runtime environment root identity is unavailable",
                self.environment_source.as_str()
            )),
        }
    }
}

/// Canonicalize one absolute managed runtime directory, optionally creating it first.
/// 规范化单个绝对受管运行时目录，并可选择先创建该目录。
fn canonicalize_managed_runtime_directory(
    path: &Path,
    label: &str,
    create: bool,
) -> Result<PathBuf, String> {
    if !path.is_absolute() {
        return Err(format!("{label} must be an absolute path"));
    }
    if create {
        fs::create_dir_all(path).map_err(|error| {
            format!(
                "failed to create {label} {}: {error}",
                render_host_visible_path(path)
            )
        })?;
    }
    let canonical = fs::canonicalize(path).map_err(|error| {
        format!(
            "failed to canonicalize {label} {}: {error}",
            render_host_visible_path(path)
        )
    })?;
    // Every managed root must have a stable spelling consumable by Lua and managed child runtimes.
    // 每个受管根都必须具备可由 Lua 与受管子运行时消费的稳定写法。
    normalize_host_input_path_text(&canonical.to_string_lossy())
        .map_err(|error| format!("{label}: {error}"))?;
    ensure_managed_runtime_directory(&canonical, label)?;
    Ok(canonical)
}

/// Require one managed runtime root path to identify a real directory.
/// 要求单个受管运行时根路径标识真实目录。
fn ensure_managed_runtime_directory(path: &Path, label: &str) -> Result<(), String> {
    let metadata = fs::metadata(path).map_err(|error| {
        format!(
            "failed to inspect {label} {}: {error}",
            render_host_visible_path(path)
        )
    })?;
    if !metadata.is_dir() {
        return Err(format!(
            "{label} is not a directory: {}",
            render_host_visible_path(path)
        ));
    }
    Ok(())
}

/// Machine-readable capability for persistent managed Python and Node sessions.
/// 受管 Python 与 Node 持久会话的机器可读能力。
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct ManagedRuntimePersistentSessionCapability {
    /// Whether `session.open` is supported without creating any runtime resources first.
    /// 是否可在不预先创建任何运行时资源的情况下支持 `session.open`。
    pub supported: bool,
    /// Rust target operating-system identifier for the current binary.
    /// 当前二进制的 Rust 目标操作系统标识。
    pub target_os: String,
    /// Rust target CPU-architecture identifier for the current binary.
    /// 当前二进制的 Rust 目标 CPU 架构标识。
    pub target_arch: String,
    /// Stable unsupported reason code; absent for supported targets.
    /// 稳定的不支持原因码；受支持目标上不存在。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Return the current target's persistent managed-session capability without side effects.
/// 无副作用地返回当前目标的受管持久会话能力。
///
/// This function accepts no parameters and performs no environment, snapshot, or process work.
/// 本函数不接收参数，也不会执行环境、快照或进程操作。
///
/// Returns an unsupported result only for Windows ARM among officially supported target families.
/// 在官方支持的目标族中，仅 Windows ARM 返回不支持结果。
pub fn current_managed_runtime_persistent_session_capability()
-> ManagedRuntimePersistentSessionCapability {
    // Windows ARM is the sole explicitly unsupported target and must fail before resource creation.
    // Windows ARM 是唯一明确不支持的目标，且必须在资源创建前失败。
    let windows_arm = cfg!(all(windows, target_arch = "aarch64"));
    // Linux/macOS share descriptor-anchored primitives; non-ARM Windows uses native handles.
    // Linux/macOS 共享描述符锚定原语；非 ARM Windows 使用原生句柄。
    let supported_family = cfg!(any(target_os = "linux", target_os = "macos"))
        || cfg!(all(windows, not(target_arch = "aarch64")));
    ManagedRuntimePersistentSessionCapability {
        supported: supported_family && !windows_arm,
        target_os: env::consts::OS.to_string(),
        target_arch: env::consts::ARCH.to_string(),
        reason: windows_arm.then(|| WINDOWS_ARM_PERSISTENT_SESSION_UNSUPPORTED_REASON.to_string()),
    }
}

/// Tests for the stable persistent-session platform capability contract.
/// 稳定持久会话平台能力契约测试。
#[cfg(test)]
mod persistent_session_capability_tests {
    use super::current_managed_runtime_persistent_session_capability;

    /// Verify every supported production target reports an enabled structured capability.
    /// 验证每个受支持生产目标都会报告已启用的结构化能力。
    #[cfg(any(
        target_os = "linux",
        target_os = "macos",
        all(windows, not(target_arch = "aarch64"))
    ))]
    #[test]
    fn supported_target_reports_persistent_sessions() {
        let capability = current_managed_runtime_persistent_session_capability();

        assert!(capability.supported);
        assert_eq!(capability.target_os, std::env::consts::OS);
        assert_eq!(capability.target_arch, std::env::consts::ARCH);
        assert_eq!(capability.reason, None);
    }

    /// Verify Windows ARM reports the sole stable unsupported reason without ambiguity.
    /// 验证 Windows ARM 会无歧义地报告唯一稳定的不支持原因。
    #[cfg(all(windows, target_arch = "aarch64"))]
    #[test]
    fn windows_arm_reports_stable_unsupported_reason() {
        let capability = current_managed_runtime_persistent_session_capability();

        assert!(!capability.supported);
        assert_eq!(capability.target_os, "windows");
        assert_eq!(capability.target_arch, "aarch64");
        assert_eq!(
            capability.reason.as_deref(),
            Some(super::WINDOWS_ARM_PERSISTENT_SESSION_UNSUPPORTED_REASON)
        );
    }
}

/// Process-local sequence used to isolate unpublished environment build directories.
/// 用于隔离未发布环境构建目录的进程内序号。
static NEXT_MANAGED_RUNTIME_BUILD_SEQUENCE: AtomicU64 = AtomicU64::new(0);
/// Maximum atomic build-directory attempts used to bypass stale crash remnants.
/// 用于绕过崩溃残留的最大原子构建目录尝试次数。
const MAX_MANAGED_RUNTIME_BUILD_DIR_ATTEMPTS: usize = 64;
/// Maximum replaced-environment backups retained by the process-wide recovery worker.
/// 进程级恢复 Worker 最多保留的已替换环境备份数量。
const MAX_MANAGED_RUNTIME_BACKUP_RECOVERY_RECORDS: usize = 1_024;
/// Fixed delay between failed replaced-environment recovery attempts.
/// 已替换环境恢复失败后的固定重试间隔。
const MANAGED_RUNTIME_BACKUP_RECOVERY_RETRY_DELAY: Duration = Duration::from_millis(100);
/// Minimum Node.js version supported by the asynchronous ESM worker protocol.
/// 异步 ESM Worker 协议支持的最低 Node.js 版本。
const MIN_MANAGED_NODE_RUNTIME_VERSION: &str = "22.0.0";

/// Process-wide durable owner for replaced managed-environment recovery records.
/// 已替换受管环境恢复记录的进程级持久所有者。
struct ManagedRuntimeBackupRecoveryCenter {
    /// Recovery records retained across transient filesystem failures.
    /// 跨瞬态文件系统失败保留的恢复记录。
    records: Mutex<VecDeque<ManagedRuntimeBackupRecoveryRecord>>,
    /// Notification waking the single recovery worker after one record is published.
    /// 单个记录发布后唤醒唯一恢复 Worker 的通知量。
    changed: Condvar,
    /// Total reserved records, including records still owned by a publication transaction.
    /// 已预留记录总数，包括仍由发布事务拥有的记录。
    reserved: Arc<AtomicUsize>,
}

/// One pre-reserved capacity permit guaranteeing lossless recovery handoff.
/// 保证恢复任务无损交接的单个预留容量许可。
struct ManagedRuntimeBackupRecoveryPermit {
    /// Shared reservation counter decremented only after final recovery completion.
    /// 仅在最终恢复完成后递减的共享预留计数器。
    reserved: Arc<AtomicUsize>,
}

impl Drop for ManagedRuntimeBackupRecoveryPermit {
    /// Release one replaced-environment recovery reservation.
    /// 释放单个已替换环境恢复预留。
    fn drop(&mut self) {
        self.reserved.fetch_sub(1, Ordering::AcqRel);
    }
}

/// Required recovery action after an environment replacement transaction leaves one backup.
/// 环境替换事务留下单个备份后所需的恢复动作。
enum ManagedRuntimeBackupRecoveryAction {
    /// Delete an obsolete backup after the new environment was committed successfully.
    /// 新环境成功提交后删除已过时备份。
    RemoveCommittedBackup,
    /// Restore the old environment name after publication and synchronous rollback both failed.
    /// 发布与同步回滚均失败后恢复旧环境名称。
    RestoreFailedPublication {
        /// Exact plan whose stable environment name must be restored or superseded safely.
        /// 必须被安全恢复或替代的稳定环境名称对应精确计划。
        plan: Box<ManagedRuntimeEnvPlan>,
    },
}

/// Identity-bound replaced-environment backup retained until recovery succeeds.
/// 通过身份绑定并保留到恢复成功的已替换环境备份。
struct ManagedRuntimeBackupRecoveryRecord {
    /// Unique same-parent backup path created by the publication transaction.
    /// 发布事务创建的唯一同父级备份路径。
    backup_path: PathBuf,
    /// Native identity captured before the original environment name was moved.
    /// 原环境名称移动前捕获的平台原生身份。
    identity: ManagedFilesystemObjectIdentity,
    /// Recovery action selected from the transaction commit state.
    /// 根据事务提交状态选择的恢复动作。
    action: ManagedRuntimeBackupRecoveryAction,
    /// Capacity ownership retained through every retry.
    /// 跨越每次重试保留的容量所有权。
    _permit: ManagedRuntimeBackupRecoveryPermit,
    /// Whether the first persistent failure has already been logged.
    /// 是否已经记录首次持久失败。
    error_reported: bool,
}

/// Cross-process advisory file lock held for one exact managed environment construction.
/// 为单个精确受管环境构建持有的跨进程建议文件锁。
struct ManagedRuntimeEnvFileLock {
    /// Open lock-file handle whose lifetime owns the operating-system lock.
    /// 其生命周期拥有操作系统锁的已打开锁文件句柄。
    file: File,
    /// Stable host-visible path used only for unlock diagnostics.
    /// 仅用于解锁诊断的稳定宿主可见路径。
    path: PathBuf,
}

impl Drop for ManagedRuntimeEnvFileLock {
    /// Release the operating-system environment lock without panicking during teardown.
    /// 在清理期间释放操作系统环境锁且不触发 panic。
    fn drop(&mut self) {
        if let Err(error) = unlock_managed_runtime_env_file(&self.file) {
            crate::runtime_logging::warn(format!(
                "[LuaSkill:warn] failed to unlock managed runtime environment {}: {error}",
                render_host_visible_path(&self.path)
            ));
        }
    }
}

/// Shared cross-process lifecycle lease retained while one managed environment is in active use.
/// 当一个受管环境处于活动使用状态时保留的跨进程共享生命周期租约。
#[derive(Debug)]
pub(crate) struct ManagedRuntimeEnvLease {
    /// Operating-system lease guard whose lifetime prevents environment publication or replacement.
    /// 其生命周期阻止环境发布或替换的操作系统租约保护器。
    _guard: ManagedRuntimeEnvLeaseFileLock,
}

/// Operating-system lock owner shared by active and publishing environment lease modes.
/// 由活动环境租约模式与发布环境租约模式共同使用的操作系统锁所有者。
#[derive(Debug)]
struct ManagedRuntimeEnvLeaseFileLock {
    /// Open lease-file handle whose lifetime owns the selected shared or exclusive lock.
    /// 其生命周期拥有选定共享锁或独占锁的已打开租约文件句柄。
    file: File,
    /// Stable host-visible lease path used only for unlock diagnostics.
    /// 仅用于解锁诊断的稳定宿主可见租约路径。
    path: PathBuf,
}

impl Drop for ManagedRuntimeEnvLeaseFileLock {
    /// Release one lifecycle lease without panicking during environment or process teardown.
    /// 在环境或进程清理期间释放一个生命周期租约且不触发 panic。
    fn drop(&mut self) {
        if let Err(error) = unlock_managed_runtime_env_lease_file(&self.file) {
            crate::runtime_logging::warn(format!(
                "[LuaSkill:warn] failed to unlock managed runtime environment lifecycle lease {}: {error}",
                render_host_visible_path(&self.path)
            ));
        }
    }
}

/// Return the process-wide weak registry of per-environment construction locks.
/// 返回进程级每环境构建锁弱引用注册表。
fn managed_runtime_env_lock_registry() -> &'static Mutex<HashMap<PathBuf, Weak<Mutex<()>>>> {
    static REGISTRY: OnceLock<Mutex<HashMap<PathBuf, Weak<Mutex<()>>>>> = OnceLock::new();
    REGISTRY.get_or_init(|| Mutex::new(HashMap::new()))
}

/// Return one shared construction lock for the exact resolved environment directory.
/// 返回精确已解析环境目录对应的共享构建锁。
fn managed_runtime_env_lock(env_dir: &Path) -> Arc<Mutex<()>> {
    // Registry guard recovered after poisoning so one failed builder cannot wedge all environments.
    // 在锁中毒后恢复注册表保护，避免单个失败构建器阻塞全部环境。
    let mut registry = managed_runtime_env_lock_registry()
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    registry.retain(|_, lock| lock.strong_count() > 0);
    if let Some(lock) = registry.get(env_dir).and_then(Weak::upgrade) {
        return lock;
    }
    // Fresh lock published as a weak entry so unused environment identities do not leak forever.
    // 以弱引用条目发布的新锁，避免未使用环境身份永久泄漏。
    let lock = Arc::new(Mutex::new(()));
    registry.insert(env_dir.to_path_buf(), Arc::downgrade(&lock));
    lock
}

/// Return the process-wide replaced-environment recovery center, creating its worker once.
/// 返回进程级已替换环境恢复中心，并仅创建一次其 Worker。
fn managed_runtime_backup_recovery_center()
-> Result<Arc<ManagedRuntimeBackupRecoveryCenter>, String> {
    static CENTER: OnceLock<Result<Arc<ManagedRuntimeBackupRecoveryCenter>, String>> =
        OnceLock::new();
    match CENTER.get_or_init(initialize_managed_runtime_backup_recovery_center) {
        Ok(center) => Ok(Arc::clone(center)),
        Err(error) => Err(error.clone()),
    }
}

/// Create the durable recovery queue and its single process-wide worker.
/// 创建持久恢复队列及其唯一进程级 Worker。
fn initialize_managed_runtime_backup_recovery_center()
-> Result<Arc<ManagedRuntimeBackupRecoveryCenter>, String> {
    // Shared reservation counter retained independently from transient publication callers.
    // 独立于瞬态发布调用方保留的共享预留计数器。
    let reserved = Arc::new(AtomicUsize::new(0));
    // Center published only after its worker starts successfully.
    // 仅在 Worker 成功启动后发布的恢复中心。
    let center = Arc::new(ManagedRuntimeBackupRecoveryCenter {
        records: Mutex::new(VecDeque::new()),
        changed: Condvar::new(),
        reserved,
    });
    let worker_center = Arc::clone(&center);
    thread::Builder::new()
        .name("luaskills-managed-env-backup-recovery".to_string())
        .spawn(move || run_managed_runtime_backup_recovery_worker(worker_center))
        .map_err(|error| {
            format!("failed to start managed environment backup recovery worker: {error}")
        })?;
    Ok(center)
}

/// Reserve one bounded recovery slot before any published environment name is mutated.
/// 在修改任何已发布环境名称前预留一个有界恢复槽。
///
/// Returns the durable center and one permit that can be transferred into a retry record.
/// 返回持久恢复中心及一个可移交到重试记录的许可。
fn reserve_managed_runtime_backup_recovery_slot() -> Result<
    (
        Arc<ManagedRuntimeBackupRecoveryCenter>,
        ManagedRuntimeBackupRecoveryPermit,
    ),
    String,
> {
    let center = managed_runtime_backup_recovery_center()?;
    center
        .reserved
        .fetch_update(Ordering::AcqRel, Ordering::Acquire, |reserved| {
            (reserved < MAX_MANAGED_RUNTIME_BACKUP_RECOVERY_RECORDS).then_some(reserved + 1)
        })
        .map_err(|reserved| {
            format!(
                "managed environment backup recovery capacity is exhausted; reserved={reserved} max={MAX_MANAGED_RUNTIME_BACKUP_RECOVERY_RECORDS}"
            )
        })?;
    let permit = ManagedRuntimeBackupRecoveryPermit {
        reserved: Arc::clone(&center.reserved),
    };
    Ok((center, permit))
}

impl ManagedRuntimeBackupRecoveryCenter {
    /// Publish one pre-reserved recovery record without any fallible filesystem work.
    /// 发布单个已预留恢复记录，且不执行任何可失败文件系统操作。
    ///
    /// `record` carries both exact backup identity and its capacity permit.
    /// `record` 同时携带精确备份身份与容量许可。
    fn enqueue(&self, record: ManagedRuntimeBackupRecoveryRecord) {
        let mut records = self
            .records
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        records.push_back(record);
        self.changed.notify_one();
    }

    /// Wait for and remove one retained recovery record.
    /// 等待并移除单个已保留恢复记录。
    fn wait_next(&self) -> ManagedRuntimeBackupRecoveryRecord {
        let mut records = self
            .records
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        while records.is_empty() {
            records = self
                .changed
                .wait(records)
                .unwrap_or_else(std::sync::PoisonError::into_inner);
        }
        records
            .pop_front()
            .expect("non-empty managed environment recovery queue must yield one record")
    }
}

/// Run the process-wide replaced-environment recovery worker forever.
/// 永久运行进程级已替换环境恢复 Worker。
///
/// `center` is process-static through the global once cell; every record remains owned outside the
/// fallible recovery call so an error or panic cannot discard its backup identity or permit.
/// `center` 通过全局一次性单元具备进程静态生命周期；每个记录都在可失败恢复调用之外保持所有权，
/// 因此错误或 panic 不会丢失其备份身份或许可。
fn run_managed_runtime_backup_recovery_worker(center: Arc<ManagedRuntimeBackupRecoveryCenter>) {
    loop {
        let mut record = center.wait_next();
        let recovery = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            recover_managed_runtime_backup(&mut record)
        }));
        match recovery {
            Ok(Ok(())) => {
                // Dropping the completed record releases its bounded capacity reservation.
                // 丢弃已完成记录会释放其有界容量预留。
                drop(record);
            }
            Ok(Err(error)) => {
                if !record.error_reported {
                    crate::runtime_logging::warn(format!(
                        "[LuaSkill:warn] managed environment backup recovery remains pending for {}: {error}",
                        render_host_visible_path(&record.backup_path)
                    ));
                    record.error_reported = true;
                }
                thread::sleep(MANAGED_RUNTIME_BACKUP_RECOVERY_RETRY_DELAY);
                center.enqueue(record);
            }
            Err(_) => {
                if !record.error_reported {
                    crate::runtime_logging::warn(format!(
                        "[LuaSkill:warn] managed environment backup recovery panicked and remains pending for {}",
                        render_host_visible_path(&record.backup_path)
                    ));
                    record.error_reported = true;
                }
                thread::sleep(MANAGED_RUNTIME_BACKUP_RECOVERY_RETRY_DELAY);
                center.enqueue(record);
            }
        }
    }
}

/// Complete the exact action retained by one replaced-environment recovery record.
/// 完成单个已替换环境恢复记录保留的精确动作。
///
/// Returns unit only after the obsolete backup is removed or the failed publication name is
/// restored/safely superseded by a ready environment.
/// 仅在过时备份已删除，或失败发布名称已恢复/被就绪环境安全替代后返回空值。
fn recover_managed_runtime_backup(
    record: &mut ManagedRuntimeBackupRecoveryRecord,
) -> Result<(), String> {
    match &record.action {
        ManagedRuntimeBackupRecoveryAction::RemoveCommittedBackup => {
            remove_identity_bound_managed_runtime_backup(&record.backup_path, &record.identity)
        }
        ManagedRuntimeBackupRecoveryAction::RestoreFailedPublication { plan } => {
            recover_failed_managed_runtime_publication(plan, &record.backup_path, &record.identity)
        }
    }
}

/// Remove one obsolete backup only while its native directory identity remains unchanged.
/// 仅在平台原生目录身份未变化时删除单个过时备份。
fn remove_identity_bound_managed_runtime_backup(
    backup_path: &Path,
    identity: &ManagedFilesystemObjectIdentity,
) -> Result<(), String> {
    match fs::symlink_metadata(backup_path) {
        Ok(_) => {}
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
        Err(error) => {
            return Err(format!(
                "failed to inspect replaced managed environment {}: {error}",
                render_managed_runtime_path(backup_path)
            ));
        }
    }
    validate_managed_directory_identity(backup_path, identity, "replaced managed environment")?;
    match fs::remove_dir_all(backup_path) {
        Ok(()) => Ok(()),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(error) => Err(format!(
            "failed to remove replaced managed environment {}: {error}",
            render_managed_runtime_path(backup_path)
        )),
    }
}

/// Restore an old environment name after publication and immediate rollback both failed.
/// 在发布与即时回滚均失败后恢复旧环境名称。
fn recover_failed_managed_runtime_publication(
    plan: &ManagedRuntimeEnvPlan,
    backup_path: &Path,
    identity: &ManagedFilesystemObjectIdentity,
) -> Result<(), String> {
    // Process-local and cross-process construction locks serialize recovery with every installer.
    // 进程内及跨进程构建锁使恢复与每个安装器串行化。
    let build_lock = managed_runtime_env_lock(&plan.env_dir);
    let _build_guard = build_lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let _file_lock = acquire_managed_runtime_env_file_lock(plan)?;
    if managed_env_is_ready(plan)? {
        // Another installer safely superseded the failed transaction; only the old backup remains.
        // 另一个安装器已安全替代失败事务；此时只剩旧备份需要删除。
        return remove_identity_bound_managed_runtime_backup(backup_path, identity);
    }
    match fs::symlink_metadata(&plan.env_dir) {
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
        Ok(_) => {
            return Err(format!(
                "cannot restore replaced managed environment while target exists: {}",
                render_managed_runtime_path(&plan.env_dir)
            ));
        }
        Err(error) => {
            return Err(format!(
                "failed to inspect managed environment recovery target {}: {error}",
                render_managed_runtime_path(&plan.env_dir)
            ));
        }
    }
    let _publish_lease = try_acquire_managed_runtime_env_publish_lease(plan)?;
    validate_managed_directory_identity(backup_path, identity, "replaced managed environment")?;
    fs::rename(backup_path, &plan.env_dir).map_err(|error| {
        format!(
            "failed to restore replaced managed environment {} as {}: {error}",
            render_managed_runtime_path(backup_path),
            render_managed_runtime_path(&plan.env_dir)
        )
    })
}

/// Acquire one cross-process exclusive construction lock for an exact environment plan.
/// 为一个精确环境计划获取跨进程独占构建锁。
///
/// `plan` supplies the stable environment parent and hash used to derive the lock-file identity.
/// `plan` 提供用于派生锁文件身份的稳定环境父目录与哈希。
///
/// Returns a guard whose drop releases the OS lock, or a host-visible filesystem/locking error.
/// 返回析构时释放操作系统锁的保护对象，或宿主可见的文件系统/加锁错误。
fn acquire_managed_runtime_env_file_lock(
    plan: &ManagedRuntimeEnvPlan,
) -> Result<ManagedRuntimeEnvFileLock, String> {
    let parent = plan.env_dir.parent().ok_or_else(|| {
        format!(
            "managed env directory has no parent: {}",
            render_managed_runtime_path(&plan.env_dir)
        )
    })?;
    fs::create_dir_all(parent).map_err(|error| {
        format!(
            "Failed to create managed environment parent {}: {error}",
            render_managed_runtime_path(parent)
        )
    })?;
    // Persistent lock file is namespaced by runtime/version parent plus the exact environment hash.
    // 持久锁文件由运行时/版本父目录与精确环境哈希共同划分命名空间。
    let path = parent.join(format!(".luaskills-env-{}.lock", plan.env_hash));
    let file = OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(&path)
        .map_err(|error| {
            format!(
                "Failed to open managed environment lock {}: {error}",
                render_managed_runtime_path(&path)
            )
        })?;
    lock_managed_runtime_env_file(&file).map_err(|error| {
        format!(
            "Failed to lock managed environment {}: {error}",
            render_managed_runtime_path(&path)
        )
    })?;
    Ok(ManagedRuntimeEnvFileLock { file, path })
}

/// Ensure one environment, acquire its shared lifecycle lease, and revalidate readiness.
/// 确保一个环境就绪、获取其共享生命周期租约，并重新校验就绪状态。
///
/// `plan` identifies the exact environment whose published directory must remain stable.
/// `plan` 标识其已发布目录必须保持稳定的精确环境。
///
/// Returns a shared lease only after the expected marker is observed while that lease is held.
/// 仅在持有租约期间观察到期望 marker 后返回共享租约。
pub(crate) fn acquire_ready_managed_env_lease(
    plan: &ManagedRuntimeEnvPlan,
) -> Result<ManagedRuntimeEnvLease, String> {
    ensure_managed_env(plan)?;
    // SharedGuard closes the ensure-to-use replacement window before marker revalidation.
    // SharedGuard 会在 marker 复验前关闭从 ensure 到使用之间的替换窗口。
    let guard = acquire_managed_runtime_env_shared_lease(plan)?;
    if !managed_env_is_ready(plan)? {
        return Err(format!(
            "managed runtime environment changed before lifecycle lease acquisition: {}",
            render_managed_runtime_path(&plan.env_dir)
        ));
    }
    Ok(ManagedRuntimeEnvLease { _guard: guard })
}

/// Open the stable per-environment lifecycle lease file used by shared users and publishers.
/// 打开由共享使用方与发布方共同使用的稳定每环境生命周期租约文件。
///
/// `plan` supplies the exact environment parent and identity hash.
/// `plan` 提供精确环境父目录与身份哈希。
///
/// Returns the open file and its diagnostic path without acquiring a lock.
/// 返回尚未加锁的已打开文件及其诊断路径。
fn open_managed_runtime_env_lease_file(
    plan: &ManagedRuntimeEnvPlan,
) -> Result<(File, PathBuf), String> {
    // Stable environment parent that owns both the published directory and lifecycle lease file.
    // 同时承载已发布目录与生命周期租约文件的稳定环境父目录。
    let parent = plan.env_dir.parent().ok_or_else(|| {
        format!(
            "managed env directory has no parent: {}",
            render_managed_runtime_path(&plan.env_dir)
        )
    })?;
    fs::create_dir_all(parent).map_err(|error| {
        format!(
            "Failed to create managed environment parent {}: {error}",
            render_managed_runtime_path(parent)
        )
    })?;
    // LeasePath is separate from the construction lock so active use never blocks build staging.
    // LeasePath 与构建锁相互独立，因此活动使用不会阻止构建暂存。
    let path = parent.join(format!(".luaskills-env-{}.lease", plan.env_hash));
    // Read-write handle required by both Unix flock and Windows byte-range locking primitives.
    // Unix flock 与 Windows 字节范围锁原语共同需要的读写句柄。
    let file = OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(&path)
        .map_err(|error| {
            format!(
                "Failed to open managed environment lifecycle lease {}: {error}",
                render_managed_runtime_path(&path)
            )
        })?;
    Ok((file, path))
}

/// Acquire one blocking shared lifecycle lease for an active managed environment user.
/// 为一个活动受管环境使用方获取阻塞式共享生命周期租约。
///
/// `plan` identifies the stable lease file shared with environment publication.
/// `plan` 标识与环境发布共享的稳定租约文件。
///
/// Returns a guard that releases the shared operating-system lock on drop.
/// 返回一个在析构时释放共享操作系统锁的保护器。
fn acquire_managed_runtime_env_shared_lease(
    plan: &ManagedRuntimeEnvPlan,
) -> Result<ManagedRuntimeEnvLeaseFileLock, String> {
    // Lease handle and stable path retained together for ownership and diagnostics.
    // 为所有权与诊断共同保留的租约句柄及稳定路径。
    let (file, path) = open_managed_runtime_env_lease_file(plan)?;
    lock_managed_runtime_env_lease_shared(&file).map_err(|error| {
        format!(
            "Failed to acquire shared managed environment lifecycle lease {}: {error}",
            render_managed_runtime_path(&path)
        )
    })?;
    Ok(ManagedRuntimeEnvLeaseFileLock { file, path })
}

/// Try to acquire one exclusive lifecycle lease before touching a published environment directory.
/// 在接触已发布环境目录前尝试获取一个独占生命周期租约。
///
/// `plan` identifies the environment whose active users must prevent replacement.
/// `plan` 标识其活动使用方必须阻止替换的环境。
///
/// Returns immediately with a stable busy error when any shared lifecycle lease is active.
/// 任一共享生命周期租约处于活动状态时立即返回稳定 busy 错误。
fn try_acquire_managed_runtime_env_publish_lease(
    plan: &ManagedRuntimeEnvPlan,
) -> Result<ManagedRuntimeEnvLeaseFileLock, String> {
    // Lease handle and stable path used for the immediate exclusive publication attempt.
    // 用于立即尝试独占发布的租约句柄及稳定路径。
    let (file, path) = open_managed_runtime_env_lease_file(plan)?;
    match try_lock_managed_runtime_env_lease_exclusive(&file) {
        Ok(true) => Ok(ManagedRuntimeEnvLeaseFileLock { file, path }),
        Ok(false) => Err(format!(
            "managed runtime environment is busy with active lifecycle leases: {}",
            render_managed_runtime_path(&plan.env_dir)
        )),
        Err(error) => Err(format!(
            "Failed to acquire exclusive managed environment lifecycle lease {}: {error}",
            render_managed_runtime_path(&path)
        )),
    }
}

/// Block until one exclusive operating-system lock is held on the supplied file.
/// 阻塞直至在提供的文件上持有一个操作系统独占锁。
///
/// `file` remains open for the complete lock lifetime.
/// `file` 在完整锁生命周期内保持打开。
#[cfg(unix)]
fn lock_managed_runtime_env_file(file: &File) -> Result<(), std::io::Error> {
    use std::os::fd::AsRawFd;

    loop {
        let status = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX) };
        if status == 0 {
            return Ok(());
        }
        let error = std::io::Error::last_os_error();
        if error.kind() != std::io::ErrorKind::Interrupted {
            return Err(error);
        }
    }
}

/// Release one Unix advisory environment lock.
/// 释放一个 Unix 建议环境锁。
#[cfg(unix)]
fn unlock_managed_runtime_env_file(file: &File) -> Result<(), std::io::Error> {
    use std::os::fd::AsRawFd;

    let status = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_UN) };
    if status == 0 {
        Ok(())
    } else {
        Err(std::io::Error::last_os_error())
    }
}

/// Block until one exclusive Windows byte-range lock is held on the supplied file.
/// 阻塞直至在提供的文件上持有一个 Windows 独占字节范围锁。
#[cfg(windows)]
fn lock_managed_runtime_env_file(file: &File) -> Result<(), std::io::Error> {
    use std::os::windows::io::AsRawHandle;
    use windows_sys::Win32::Storage::FileSystem::{LOCKFILE_EXCLUSIVE_LOCK, LockFileEx};
    use windows_sys::Win32::System::IO::OVERLAPPED;

    // Zero offset plus the full 64-bit range makes every contender lock the same file identity.
    // 零偏移加完整 64 位范围，使每个竞争方都锁定同一文件身份。
    let mut overlapped = unsafe { std::mem::zeroed::<OVERLAPPED>() };
    let status = unsafe {
        LockFileEx(
            file.as_raw_handle() as _,
            LOCKFILE_EXCLUSIVE_LOCK,
            0,
            u32::MAX,
            u32::MAX,
            &mut overlapped,
        )
    };
    if status != 0 {
        Ok(())
    } else {
        Err(std::io::Error::last_os_error())
    }
}

/// Release one Windows byte-range environment lock.
/// 释放一个 Windows 字节范围环境锁。
#[cfg(windows)]
fn unlock_managed_runtime_env_file(file: &File) -> Result<(), std::io::Error> {
    use std::os::windows::io::AsRawHandle;
    use windows_sys::Win32::Storage::FileSystem::UnlockFileEx;
    use windows_sys::Win32::System::IO::OVERLAPPED;

    let mut overlapped = unsafe { std::mem::zeroed::<OVERLAPPED>() };
    let status = unsafe {
        UnlockFileEx(
            file.as_raw_handle() as _,
            0,
            u32::MAX,
            u32::MAX,
            &mut overlapped,
        )
    };
    if status != 0 {
        Ok(())
    } else {
        Err(std::io::Error::last_os_error())
    }
}

/// Reject managed environment construction on platforms without a reliable file-lock primitive.
/// 在缺少可靠文件锁原语的平台上拒绝受管环境构建。
#[cfg(not(any(unix, windows)))]
fn lock_managed_runtime_env_file(_file: &File) -> Result<(), std::io::Error> {
    Err(std::io::Error::new(
        std::io::ErrorKind::Unsupported,
        "managed runtime cross-process file locking is unsupported on this platform",
    ))
}

/// No-op signature counterpart for unsupported platforms where acquisition always fails.
/// 在获取始终失败的不受支持平台上提供同签名空操作对应函数。
#[cfg(not(any(unix, windows)))]
fn unlock_managed_runtime_env_file(_file: &File) -> Result<(), std::io::Error> {
    Ok(())
}

/// Block until one Unix shared lifecycle lease is held on the supplied file.
/// 阻塞直至在提供的文件上持有一个 Unix 共享生命周期租约。
#[cfg(unix)]
fn lock_managed_runtime_env_lease_shared(file: &File) -> Result<(), std::io::Error> {
    use std::os::fd::AsRawFd;

    loop {
        // Kernel flock result retried only when interrupted before lock acquisition completes.
        // 仅当锁获取完成前被中断时重试的内核 flock 结果。
        let status = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_SH) };
        if status == 0 {
            return Ok(());
        }
        // Exact operating-system error used to distinguish retryable interruption from failure.
        // 用于区分可重试中断与失败的精确操作系统错误。
        let error = std::io::Error::last_os_error();
        if error.kind() != std::io::ErrorKind::Interrupted {
            return Err(error);
        }
    }
}

/// Try one nonblocking Unix exclusive lifecycle lease acquisition.
/// 尝试一次非阻塞 Unix 独占生命周期租约获取。
///
/// Returns `false` only when another shared or exclusive lease currently owns the file.
/// 仅当另一个共享或独占租约当前拥有该文件时返回 `false`。
#[cfg(unix)]
fn try_lock_managed_runtime_env_lease_exclusive(file: &File) -> Result<bool, std::io::Error> {
    use std::os::fd::AsRawFd;

    loop {
        // Nonblocking kernel flock result preserving contention as a normal busy outcome.
        // 将锁竞争保留为正常 busy 结果的非阻塞内核 flock 结果。
        let status = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) };
        if status == 0 {
            return Ok(true);
        }
        // Exact operating-system error classified into contention, interruption, or hard failure.
        // 被分类为竞争、中断或硬失败的精确操作系统错误。
        let error = std::io::Error::last_os_error();
        match error.kind() {
            std::io::ErrorKind::WouldBlock => return Ok(false),
            std::io::ErrorKind::Interrupted => continue,
            _ => return Err(error),
        }
    }
}

/// Release one Unix shared or exclusive lifecycle lease.
/// 释放一个 Unix 共享或独占生命周期租约。
#[cfg(unix)]
fn unlock_managed_runtime_env_lease_file(file: &File) -> Result<(), std::io::Error> {
    use std::os::fd::AsRawFd;

    // Kernel unlock result surfaced to the guard drop path for diagnostic logging.
    // 向保护器析构路径暴露以便诊断记录的内核解锁结果。
    let status = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_UN) };
    if status == 0 {
        Ok(())
    } else {
        Err(std::io::Error::last_os_error())
    }
}

/// Block until one Windows shared lifecycle byte-range lease is held.
/// 阻塞直至持有一个 Windows 共享生命周期字节范围租约。
#[cfg(windows)]
fn lock_managed_runtime_env_lease_shared(file: &File) -> Result<(), std::io::Error> {
    use std::os::windows::io::AsRawHandle;
    use windows_sys::Win32::Storage::FileSystem::LockFileEx;
    use windows_sys::Win32::System::IO::OVERLAPPED;

    // A zero flag value requests a shared lock and permits the kernel to wait for availability.
    // 零标志值请求共享锁，并允许内核等待其变为可用。
    let mut overlapped = unsafe { std::mem::zeroed::<OVERLAPPED>() };
    // Kernel lock result owning the full synthetic byte range when successful.
    // 成功时拥有完整合成字节范围的内核加锁结果。
    let status = unsafe {
        LockFileEx(
            file.as_raw_handle() as _,
            0,
            0,
            u32::MAX,
            u32::MAX,
            &mut overlapped,
        )
    };
    if status != 0 {
        Ok(())
    } else {
        Err(std::io::Error::last_os_error())
    }
}

/// Try one nonblocking Windows exclusive lifecycle byte-range lease acquisition.
/// 尝试一次非阻塞 Windows 独占生命周期字节范围租约获取。
///
/// Returns `false` only for the operating-system lock-conflict status.
/// 仅在操作系统返回锁冲突状态时返回 `false`。
#[cfg(windows)]
fn try_lock_managed_runtime_env_lease_exclusive(file: &File) -> Result<bool, std::io::Error> {
    use std::os::windows::io::AsRawHandle;
    use windows_sys::Win32::Foundation::ERROR_LOCK_VIOLATION;
    use windows_sys::Win32::Storage::FileSystem::{
        LOCKFILE_EXCLUSIVE_LOCK, LOCKFILE_FAIL_IMMEDIATELY, LockFileEx,
    };
    use windows_sys::Win32::System::IO::OVERLAPPED;

    // Zero-offset range descriptor shared with the blocking and unlock operations.
    // 与阻塞加锁及解锁操作共享的零偏移范围描述符。
    let mut overlapped = unsafe { std::mem::zeroed::<OVERLAPPED>() };
    // Immediate exclusive lock result used to distinguish contention from hard failure.
    // 用于区分竞争与硬失败的立即独占加锁结果。
    let status = unsafe {
        LockFileEx(
            file.as_raw_handle() as _,
            LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY,
            0,
            u32::MAX,
            u32::MAX,
            &mut overlapped,
        )
    };
    if status != 0 {
        return Ok(true);
    }
    // Exact Windows status classified solely by the documented lock-violation code.
    // 仅依据文档规定的锁冲突代码分类的精确 Windows 状态。
    let error = std::io::Error::last_os_error();
    if error.raw_os_error() == Some(ERROR_LOCK_VIOLATION as i32) {
        Ok(false)
    } else {
        Err(error)
    }
}

/// Release one Windows shared or exclusive lifecycle byte-range lease.
/// 释放一个 Windows 共享或独占生命周期字节范围租约。
#[cfg(windows)]
fn unlock_managed_runtime_env_lease_file(file: &File) -> Result<(), std::io::Error> {
    use std::os::windows::io::AsRawHandle;
    use windows_sys::Win32::Storage::FileSystem::UnlockFileEx;
    use windows_sys::Win32::System::IO::OVERLAPPED;

    // Zero-offset range descriptor matching the original whole-range lock acquisition.
    // 与原始全范围加锁操作匹配的零偏移范围描述符。
    let mut overlapped = unsafe { std::mem::zeroed::<OVERLAPPED>() };
    // Kernel unlock result surfaced to the guard drop path for diagnostic logging.
    // 向保护器析构路径暴露以便诊断记录的内核解锁结果。
    let status = unsafe {
        UnlockFileEx(
            file.as_raw_handle() as _,
            0,
            u32::MAX,
            u32::MAX,
            &mut overlapped,
        )
    };
    if status != 0 {
        Ok(())
    } else {
        Err(std::io::Error::last_os_error())
    }
}

/// Reject shared lifecycle leases on platforms without a reliable file-lock primitive.
/// 在缺少可靠文件锁原语的平台上拒绝共享生命周期租约。
#[cfg(not(any(unix, windows)))]
fn lock_managed_runtime_env_lease_shared(_file: &File) -> Result<(), std::io::Error> {
    Err(std::io::Error::new(
        std::io::ErrorKind::Unsupported,
        "managed runtime environment lifecycle leasing is unsupported on this platform",
    ))
}

/// Reject exclusive lifecycle leases on platforms without a reliable file-lock primitive.
/// 在缺少可靠文件锁原语的平台上拒绝独占生命周期租约。
#[cfg(not(any(unix, windows)))]
fn try_lock_managed_runtime_env_lease_exclusive(_file: &File) -> Result<bool, std::io::Error> {
    Err(std::io::Error::new(
        std::io::ErrorKind::Unsupported,
        "managed runtime environment lifecycle leasing is unsupported on this platform",
    ))
}

/// No-op unlock counterpart for unsupported lifecycle-lease platforms.
/// 为不受支持的生命周期租约平台提供空操作解锁对应函数。
#[cfg(not(any(unix, windows)))]
fn unlock_managed_runtime_env_lease_file(_file: &File) -> Result<(), std::io::Error> {
    Ok(())
}

/// Allocate one nonzero build sequence and reject exhaustion instead of wrapping.
/// 分配一个非零构建序号，并在耗尽时拒绝回绕。
fn allocate_managed_runtime_build_sequence() -> Result<u64, String> {
    NEXT_MANAGED_RUNTIME_BUILD_SEQUENCE
        .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
            current.checked_add(1)
        })
        .map(|previous| previous + 1)
        .map_err(|_| "managed runtime build sequence is exhausted".to_string())
}

/// Render one managed runtime filesystem path for user-facing error messages.
/// 为面向用户的受管运行时错误消息渲染单个文件系统路径。
fn render_managed_runtime_path(path: &Path) -> String {
    render_host_visible_path(path)
}

/// Managed child runtime kind that Lua can invoke through `vulcan.runtime.*`.
/// Lua 可通过 `vulcan.runtime.*` 调用的受管子运行时类型。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ManagedRuntimeKind {
    /// Managed Python runtime backed by a host-provided CPython bundle.
    /// 由宿主提供的 CPython 包支撑的受管 Python 运行时。
    Python,
    /// Managed Node.js runtime backed by a host-provided Node bundle.
    /// 由宿主提供的 Node 包支撑的受管 Node.js 运行时。
    Node,
}

impl ManagedRuntimeKind {
    /// Return the stable lowercase identifier used in paths and hashes.
    /// 返回用于路径与哈希的稳定小写标识符。
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Python => "python",
            Self::Node => "node",
        }
    }
}

/// Request used to compute one reusable managed runtime environment identity.
/// 用于计算一个可复用受管运行时环境身份的请求。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ManagedRuntimeEnvHashInput {
    /// Managed runtime kind used by the target environment.
    /// 目标环境使用的受管运行时类型。
    pub runtime: ManagedRuntimeKind,
    /// Exact interpreter runtime version.
    /// 精确解释器运行时版本。
    pub runtime_version: String,
    /// Normalized platform key such as `windows-x64`.
    /// 标准平台键，例如 `windows-x64`。
    pub platform: String,
    /// Package manager name such as `uv` or `pnpm`.
    /// 包管理器名称，例如 `uv` 或 `pnpm`。
    pub package_manager: String,
    /// Exact package-manager version.
    /// 精确包管理器版本。
    pub package_manager_version: String,
    /// SHA-256 digest of the dependency lockfile content.
    /// 依赖锁文件内容的 SHA-256 摘要。
    pub lock_hash: String,
    /// Optional SHA-256 digest of an additional package manifest such as package.json.
    /// package.json 等附加包清单的可选 SHA-256 摘要。
    pub package_manifest_hash: Option<String>,
    /// SHA-256 digest of the selected runtime installation manifest.
    /// 所选运行时安装清单的 SHA-256 摘要。
    pub runtime_install_manifest_hash: String,
    /// SHA-256 digest of the selected runtime executable.
    /// 所选运行时可执行文件的 SHA-256 摘要。
    pub runtime_executable_hash: String,
    /// SHA-256 digest of the selected package-manager installation manifest.
    /// 所选包管理器安装清单的 SHA-256 摘要。
    pub package_manager_install_manifest_hash: String,
    /// SHA-256 digest of the selected package-manager executable.
    /// 所选包管理器可执行文件的 SHA-256 摘要。
    pub package_manager_executable_hash: String,
}

/// Stable marker written into every managed runtime environment directory.
/// 写入每个受管运行时环境目录的稳定标记文件。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ManagedRuntimeEnvMarker {
    /// Marker schema version.
    /// 标记文件 schema 版本。
    pub schema_version: u32,
    /// Managed runtime kind stored as a stable lowercase identifier.
    /// 以稳定小写标识符保存的受管运行时类型。
    pub runtime: String,
    /// Exact interpreter runtime version.
    /// 精确解释器运行时版本。
    pub runtime_version: String,
    /// Package manager name such as `uv` or `pnpm`.
    /// 包管理器名称，例如 `uv` 或 `pnpm`。
    pub package_manager: String,
    /// Exact package-manager version.
    /// 精确包管理器版本。
    pub package_manager_version: String,
    /// Normalized platform key such as `windows-x64`.
    /// 标准平台键，例如 `windows-x64`。
    pub platform: String,
    /// SHA-256 digest of the dependency lockfile content.
    /// 依赖锁文件内容的 SHA-256 摘要。
    pub lock_hash: String,
    /// Optional SHA-256 digest of an additional package manifest such as package.json.
    /// package.json 等附加包清单的可选 SHA-256 摘要。
    pub package_manifest_hash: Option<String>,
    /// SHA-256 digest of the runtime installation manifest used to build this environment.
    /// 构建当前环境所用运行时安装清单的 SHA-256 摘要。
    pub runtime_install_manifest_hash: String,
    /// SHA-256 digest of the runtime executable used to build this environment.
    /// 构建当前环境所用运行时可执行文件的 SHA-256 摘要。
    pub runtime_executable_hash: String,
    /// SHA-256 digest of the package-manager installation manifest used for this environment.
    /// 当前环境所用包管理器安装清单的 SHA-256 摘要。
    pub package_manager_install_manifest_hash: String,
    /// SHA-256 digest of the package-manager executable used for this environment.
    /// 当前环境所用包管理器可执行文件的 SHA-256 摘要。
    pub package_manager_executable_hash: String,
    /// Environment identity hash derived from all reproducibility inputs.
    /// 由全部可复现输入派生出的环境身份哈希。
    pub env_hash: String,
}

/// Manifest written next to each managed runtime or package-manager installation.
/// 写入每个受管运行时或包管理器安装目录旁的清单。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ManagedRuntimeInstallManifest {
    /// Manifest schema version.
    /// 清单 schema 版本。
    pub schema_version: u32,
    /// Runtime or package-manager identifier such as `python`, `node`, `uv`, or `pnpm`.
    /// 运行时或包管理器标识，例如 `python`、`node`、`uv` 或 `pnpm`。
    pub runtime: String,
    /// Exact installed version.
    /// 已安装的精确版本。
    pub version: String,
    /// Platform key stored by the installation script.
    /// 安装脚本写入的平台键。
    pub platform: String,
    /// Executable path relative to the installation directory.
    /// 相对安装目录的可执行文件路径。
    pub executable: String,
}

/// Validated descriptor for one host-visible managed Python or Node installation.
/// 单个宿主可见受管 Python 或 Node 安装的已校验描述符。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ManagedRuntimeInstallDescriptor {
    /// Managed runtime kind selected by the caller.
    /// 调用方选择的受管运行时类型。
    pub runtime: ManagedRuntimeKind,
    /// Exact runtime version matched by the installation manifest.
    /// 安装清单精确匹配的运行时版本。
    pub version: String,
    /// Exact normalized platform key matched by the installation manifest.
    /// 安装清单精确匹配的规范平台键。
    pub platform: String,
    /// Canonical installation directory strictly contained by the distribution root.
    /// 严格包含在发行根内的规范安装目录。
    pub install_root: PathBuf,
    /// Canonical ordinary executable file strictly contained by the installation directory.
    /// 严格包含在安装目录内的规范普通可执行文件。
    pub executable: PathBuf,
    /// SHA-256 digest of the exact validated `runtime-manifest.json` bytes.
    /// 精确已校验 `runtime-manifest.json` 字节的 SHA-256 摘要。
    pub manifest_hash: String,
    /// SHA-256 digest of the exact resolved executable bytes.
    /// 精确已解析可执行文件字节的 SHA-256 摘要。
    pub executable_hash: String,
}

/// Internal installation identity shared by runtimes and their package managers.
/// 运行时及其包管理器共享的内部安装身份。
#[derive(Debug, Clone, PartialEq, Eq)]
struct ManagedRuntimeInstallIdentity {
    /// Canonical installation directory inside the configured distribution root.
    /// 配置发行根内的规范安装目录。
    install_root: PathBuf,
    /// Canonical executable ordinary file inside the installation directory.
    /// 安装目录内的规范普通可执行文件。
    executable: PathBuf,
    /// SHA-256 digest of the installation manifest bytes.
    /// 安装清单字节的 SHA-256 摘要。
    manifest_hash: String,
    /// SHA-256 digest of the resolved executable bytes.
    /// 已解析可执行文件字节的 SHA-256 摘要。
    executable_hash: String,
}

/// Resolved managed runtime environment plan used before creation or invocation.
/// 创建环境或调用前使用的受管运行时环境解析计划。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ManagedRuntimeEnvPlan {
    /// Managed runtime kind described by this plan.
    /// 当前计划描述的受管运行时类型。
    pub runtime: ManagedRuntimeKind,
    /// Current platform key.
    /// 当前平台键。
    pub platform: String,
    /// Canonical LuaSkills data root used for package stores, snapshots, and compatible resources.
    /// 用于包存储、快照与兼容资源的规范 LuaSkills 数据根。
    pub runtime_root: PathBuf,
    /// Canonical read-only root that supplied runtime and package-manager installations.
    /// 提供运行时及包管理器安装的规范只读根。
    pub distribution_root: PathBuf,
    /// Canonical writable root that owns reusable managed environments.
    /// 拥有可复用受管环境的规范可写根。
    pub environment_root: PathBuf,
    /// Stable source of the selected distribution root.
    /// 所选发行根的稳定来源。
    pub distribution_source: ManagedRuntimeRootSource,
    /// Stable source of the selected environment root.
    /// 所选环境根的稳定来源。
    pub environment_source: ManagedRuntimeRootSource,
    /// Canonical runtime installation directory captured by the plan.
    /// 计划捕获的规范运行时安装目录。
    pub runtime_install_root: PathBuf,
    /// Exact interpreter runtime version.
    /// 精确解释器运行时版本。
    pub runtime_version: String,
    /// Absolute interpreter executable path.
    /// 解释器可执行文件绝对路径。
    pub runtime_executable: PathBuf,
    /// SHA-256 digest of the selected runtime installation manifest.
    /// 所选运行时安装清单的 SHA-256 摘要。
    pub runtime_install_manifest_hash: String,
    /// SHA-256 digest of the selected runtime executable.
    /// 所选运行时可执行文件的 SHA-256 摘要。
    pub runtime_executable_hash: String,
    /// Package manager name such as `uv` or `pnpm`.
    /// 包管理器名称，例如 `uv` 或 `pnpm`。
    pub package_manager: String,
    /// Exact package-manager version.
    /// 精确包管理器版本。
    pub package_manager_version: String,
    /// Absolute package-manager executable path.
    /// 包管理器可执行文件绝对路径。
    pub package_manager_executable: PathBuf,
    /// Canonical package-manager installation directory captured by the plan.
    /// 计划捕获的规范包管理器安装目录。
    pub package_manager_install_root: PathBuf,
    /// SHA-256 digest of the selected package-manager installation manifest.
    /// 所选包管理器安装清单的 SHA-256 摘要。
    pub package_manager_install_manifest_hash: String,
    /// SHA-256 digest of the selected package-manager executable.
    /// 所选包管理器可执行文件的 SHA-256 摘要。
    pub package_manager_executable_hash: String,
    /// Shared immutable roots retained for identity revalidation before environment use.
    /// 在环境使用前保留以重新校验身份的共享不可变根集合。
    pub(crate) managed_runtime_roots: Arc<ManagedRuntimeRoots>,
    /// Optional package manifest path such as package.json.
    /// package.json 等可选包清单路径。
    pub package_manifest_path: Option<PathBuf>,
    /// Required lockfile path.
    /// 必需的锁文件路径。
    pub lockfile_path: PathBuf,
    /// SHA-256 digest of the dependency lockfile content.
    /// 依赖锁文件内容的 SHA-256 摘要。
    pub lock_hash: String,
    /// Optional SHA-256 digest of an additional package manifest such as package.json.
    /// package.json 等附加包清单的可选 SHA-256 摘要。
    pub package_manifest_hash: Option<String>,
    /// Environment identity hash.
    /// 环境身份哈希。
    pub env_hash: String,
    /// Directory that stores this reusable environment.
    /// 保存当前可复用环境的目录。
    pub env_dir: PathBuf,
    /// Marker expected after environment creation.
    /// 环境创建完成后期望写入的标记。
    pub expected_marker: ManagedRuntimeEnvMarker,
}

impl ManagedRuntimeEnvMarker {
    /// Build one expected marker from a hash input and precomputed environment hash.
    /// 基于哈希输入与预计算环境哈希构造一个期望标记。
    pub fn expected(input: &ManagedRuntimeEnvHashInput, env_hash: String) -> Self {
        Self {
            schema_version: MANAGED_RUNTIME_ENV_MARKER_SCHEMA_VERSION,
            runtime: input.runtime.as_str().to_string(),
            runtime_version: input.runtime_version.clone(),
            package_manager: input.package_manager.clone(),
            package_manager_version: input.package_manager_version.clone(),
            platform: input.platform.clone(),
            lock_hash: input.lock_hash.clone(),
            package_manifest_hash: input.package_manifest_hash.clone(),
            runtime_install_manifest_hash: input.runtime_install_manifest_hash.clone(),
            runtime_executable_hash: input.runtime_executable_hash.clone(),
            package_manager_install_manifest_hash: input
                .package_manager_install_manifest_hash
                .clone(),
            package_manager_executable_hash: input.package_manager_executable_hash.clone(),
            env_hash,
        }
    }
}

impl PythonRuntimePackageManager {
    /// Return the stable lowercase package-manager identifier.
    /// 返回稳定小写包管理器标识符。
    fn as_managed_runtime_str(self) -> &'static str {
        match self {
            Self::Uv => "uv",
        }
    }
}

impl NodeRuntimePackageManager {
    /// Return the stable lowercase package-manager identifier.
    /// 返回稳定小写包管理器标识符。
    fn as_managed_runtime_str(self) -> &'static str {
        match self {
            Self::Pnpm => "pnpm",
        }
    }
}

/// Return the current platform key used by managed runtime assets.
/// 返回受管运行时资产使用的当前平台键。
pub fn current_managed_runtime_platform_key() -> Result<String, String> {
    let arch_key = match std::env::consts::ARCH {
        "x86_64" => "x64",
        "aarch64" => "arm64",
        other => {
            return Err(format!(
                "unsupported managed runtime architecture: {}",
                other
            ));
        }
    };
    let os_key = match std::env::consts::OS {
        "windows" => {
            if arch_key != "x64" {
                return Err("managed runtime assets currently support Windows x64 only".to_string());
            }
            "windows"
        }
        "linux" => "linux",
        "macos" => "macos",
        other => {
            return Err(format!(
                "unsupported managed runtime operating system: {}",
                other
            ));
        }
    };
    Ok(format!("{}-{}", os_key, arch_key))
}

/// Resolve one managed Python or Node installation from a host-selected distribution root.
/// 从宿主选定发行根解析单个受管 Python 或 Node 安装。
///
/// `distribution_root` must be an existing absolute directory, `runtime` selects the fixed asset
/// family, and `version` plus `platform` must exactly match the installation manifest.
/// `distribution_root` 必须是现有绝对目录，`runtime` 选择固定资产族，`version` 与 `platform`
/// 必须精确匹配安装清单。
///
/// Returns canonical contained paths and exact manifest/executable SHA-256 identities, or an
/// explicit input, containment, manifest, file-type, or hashing error without searching `PATH`.
/// 返回规范包含路径及精确清单与可执行文件 SHA-256 身份；输入、包含关系、清单、文件类型或
/// 哈希异常时返回显式错误，且绝不搜索 `PATH`。
pub fn resolve_managed_runtime_install(
    distribution_root: &Path,
    runtime: ManagedRuntimeKind,
    version: &str,
    platform: &str,
) -> Result<ManagedRuntimeInstallDescriptor, String> {
    validate_managed_runtime_resolver_version(version)?;
    validate_managed_runtime_resolver_platform(platform)?;
    // CanonicalDistributionRoot is the sole authority boundary for this read-only resolution.
    // CanonicalDistributionRoot 是本次只读解析的唯一授权边界。
    let canonical_distribution_root = canonicalize_managed_runtime_directory(
        distribution_root,
        "managed runtime distribution root",
        false,
    )?;
    // InstallName follows the stable on-disk asset contract for the selected runtime family.
    // InstallName 遵循所选运行时资产族的稳定磁盘契约。
    let (family, install_name, expected_runtime) = match runtime {
        ManagedRuntimeKind::Python => ("python", format!("cpython-{version}-{platform}"), "python"),
        ManagedRuntimeKind::Node => ("node", format!("node-{version}-{platform}"), "node"),
    };
    // Identity binds the descriptor to exact manifest and executable bytes inside the root.
    // Identity 将描述符绑定到发行根内精确的清单及可执行文件字节。
    let identity = resolve_managed_runtime_install_identity(
        &canonical_distribution_root,
        &runtime_install_dir(&canonical_distribution_root, family, &install_name),
        expected_runtime,
        version,
        platform,
    )?;
    Ok(ManagedRuntimeInstallDescriptor {
        runtime,
        version: version.to_string(),
        platform: platform.to_string(),
        install_root: identity.install_root,
        executable: identity.executable,
        manifest_hash: identity.manifest_hash,
        executable_hash: identity.executable_hash,
    })
}

/// Validate one exact semantic runtime version before deriving an installation path.
/// 在派生安装路径前校验单个精确语义化运行时版本。
///
/// `version` is untrusted host or FFI input and must be a whitespace-free exact semantic version.
/// `version` 是不可信宿主或 FFI 输入，必须是无首尾空白的精确语义化版本。
///
/// Returns unit for valid path-safe input or a stable validation error before filesystem access.
/// 对合法且路径安全的输入返回空值，否则在文件系统访问前返回稳定校验错误。
fn validate_managed_runtime_resolver_version(version: &str) -> Result<(), String> {
    if version.is_empty() || version.trim() != version {
        return Err(
            "managed runtime version must be a non-empty exact semantic version".to_string(),
        );
    }
    Version::parse(version)
        .map(|_| ())
        .map_err(|error| format!("managed runtime version '{version}' is invalid: {error}"))
}

/// Validate one supported normalized platform key before deriving an installation path.
/// 在派生安装路径前校验单个受支持规范平台键。
///
/// `platform` is untrusted host or FFI input and must name one supported native asset target.
/// `platform` 是不可信宿主或 FFI 输入，必须命名一个受支持原生资产目标。
///
/// Returns unit for supported targets, the stable Windows ARM reason code for its explicit
/// exclusion, or a stable unsupported-platform error for every other value.
/// 对受支持目标返回空值；对明确排除的 Windows ARM 返回稳定原因码；其他值返回稳定不支持错误。
fn validate_managed_runtime_resolver_platform(platform: &str) -> Result<(), String> {
    match platform {
        "windows-x64" | "linux-x64" | "linux-arm64" | "macos-x64" | "macos-arm64" => Ok(()),
        "windows-arm64" | "windows-aarch64" | "windows-arm64ec" => {
            Err(WINDOWS_ARM_PERSISTENT_SESSION_UNSUPPORTED_REASON.to_string())
        }
        _ => Err(format!(
            "managed_runtime_platform_is_not_supported: {platform}"
        )),
    }
}

/// Compute the SHA-256 digest of one byte slice as lowercase hex.
/// 将一个字节切片计算为小写十六进制 SHA-256 摘要。
pub fn sha256_hex(bytes: &[u8]) -> String {
    let digest = Sha256::digest(bytes);
    format!("{:x}", digest)
}

/// Compute the SHA-256 digest of one file.
/// 计算单个文件的 SHA-256 摘要。
pub fn sha256_file(path: &Path) -> Result<String, String> {
    let bytes = fs::read(path).map_err(|error| {
        format!(
            "Failed to read {}: {}",
            render_managed_runtime_path(path),
            error
        )
    })?;
    Ok(sha256_hex(&bytes))
}

/// Verify one copied build input against the digest captured by its environment plan.
/// 根据环境计划捕获的摘要校验单个已复制构建输入。
///
/// `path` is the private unpublished copy, `expected_hash` is the plan-time SHA-256 digest, and
/// `label` identifies the dependency input in diagnostics.
/// `path` 是私有未发布副本，`expected_hash` 是计划阶段的 SHA-256 摘要，`label` 用于在诊断中
/// 标识依赖输入。
///
/// Returns unit only when the exact bytes consumed by the package manager match the plan identity.
/// 仅当包管理器消费的精确字节与计划身份匹配时返回空值。
fn verify_managed_runtime_build_input_hash(
    path: &Path,
    expected_hash: &str,
    label: &str,
) -> Result<(), String> {
    let actual_hash = sha256_file(path)?;
    if actual_hash != expected_hash {
        return Err(format!(
            "managed runtime {label} changed after environment planning: expected {expected_hash}, got {actual_hash}"
        ));
    }
    Ok(())
}

/// Compute one stable environment hash from reproducibility inputs.
/// 根据可复现输入计算一个稳定环境哈希。
pub fn compute_managed_runtime_env_hash(input: &ManagedRuntimeEnvHashInput) -> String {
    let mut hasher = Sha256::new();
    hash_field(
        &mut hasher,
        "schema_version",
        MANAGED_RUNTIME_ENV_MARKER_SCHEMA_VERSION.to_string(),
    );
    hash_field(&mut hasher, "runtime", input.runtime.as_str());
    hash_field(&mut hasher, "runtime_version", &input.runtime_version);
    hash_field(&mut hasher, "platform", &input.platform);
    hash_field(&mut hasher, "package_manager", &input.package_manager);
    hash_field(
        &mut hasher,
        "package_manager_version",
        &input.package_manager_version,
    );
    hash_field(&mut hasher, "lock_hash", &input.lock_hash);
    hash_field(
        &mut hasher,
        "package_manifest_hash",
        input.package_manifest_hash.as_deref().unwrap_or(""),
    );
    hash_field(
        &mut hasher,
        "runtime_install_manifest_hash",
        &input.runtime_install_manifest_hash,
    );
    hash_field(
        &mut hasher,
        "runtime_executable_hash",
        &input.runtime_executable_hash,
    );
    hash_field(
        &mut hasher,
        "package_manager_install_manifest_hash",
        &input.package_manager_install_manifest_hash,
    );
    hash_field(
        &mut hasher,
        "package_manager_executable_hash",
        &input.package_manager_executable_hash,
    );
    format!("{:x}", hasher.finalize())
}

/// Return the managed environment root for one runtime version and environment hash.
/// 返回单个运行时版本与环境哈希对应的受管环境根目录。
pub fn managed_env_dir(
    environment_root: &Path,
    runtime: ManagedRuntimeKind,
    runtime_version: &str,
    env_hash: &str,
) -> PathBuf {
    environment_root
        .join(runtime.as_str())
        .join(format!("{}-{}", runtime_prefix(runtime), runtime_version))
        .join(env_hash)
}

/// Return the marker path used by one managed runtime environment directory.
/// 返回单个受管运行时环境目录使用的标记文件路径。
pub fn managed_env_marker_path(env_dir: &Path) -> PathBuf {
    env_dir.join(".luaskills-env.json")
}

/// Inspect whether one managed environment marker path is a file without hiding filesystem probe errors.
/// 检查单个受管环境标记路径是否为文件，同时不隐藏文件系统探测错误。
///
/// The marker_path parameter is the concrete `.luaskills-env.json` path for one managed environment.
/// marker_path 参数是单个受管环境对应的具体 `.luaskills-env.json` 路径。
///
/// Return true for an existing marker file, false for a confirmed missing marker, or an explicit probe/type error.
/// 已存在标记文件返回 true，确认缺失标记返回 false；探测或类型异常时返回显式错误。
fn managed_env_marker_path_is_file(marker_path: &Path) -> Result<bool, String> {
    match fs::symlink_metadata(marker_path) {
        Ok(metadata) if metadata.file_type().is_symlink() => Err(format!(
            "Managed runtime env marker must not be a symbolic link: {}",
            render_managed_runtime_path(marker_path)
        )),
        Ok(metadata) if metadata.is_file() => Ok(true),
        Ok(_) => Err(format!(
            "Managed runtime env marker is not a file: {}",
            render_managed_runtime_path(marker_path)
        )),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
        Err(error) => Err(format!(
            "Failed to inspect managed runtime env marker {}: {}",
            render_managed_runtime_path(marker_path),
            error
        )),
    }
}

/// Inspect whether one managed-runtime directory path is a directory without hiding filesystem probe errors.
/// 检查单个受管运行时目录路径是否为目录，同时不隐藏文件系统探测错误。
///
/// The path parameter is the concrete managed runtime directory path used by an environment lifecycle step.
/// path 参数是环境生命周期步骤使用的具体受管运行时目录路径。
///
/// Return true for an existing directory, false for a confirmed missing directory, or an explicit probe/type error.
/// 已存在目录返回 true，确认缺失目录返回 false；探测或类型异常时返回显式错误。
fn managed_runtime_directory_path_is_directory(
    path: &Path,
    directory_label: &str,
) -> Result<bool, String> {
    match fs::symlink_metadata(path) {
        Ok(metadata) if metadata.file_type().is_symlink() => Err(format!(
            "{} must not be a symbolic link: {}",
            directory_label,
            render_managed_runtime_path(path)
        )),
        Ok(metadata) if metadata.is_dir() => Ok(true),
        Ok(_) => Err(format!(
            "{} is not a directory: {}",
            directory_label,
            render_managed_runtime_path(path)
        )),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
        Err(error) => Err(format!(
            "Failed to inspect {} {}: {}",
            directory_label,
            render_managed_runtime_path(path),
            error
        )),
    }
}

/// Read one managed runtime environment marker from disk.
/// 从磁盘读取一个受管运行时环境标记。
pub fn read_managed_env_marker(path: &Path) -> Result<ManagedRuntimeEnvMarker, String> {
    let text = fs::read_to_string(path).map_err(|error| {
        format!(
            "Failed to read {}: {}",
            render_managed_runtime_path(path),
            error
        )
    })?;
    serde_json::from_str(&text).map_err(|error| {
        format!(
            "Failed to parse {}: {}",
            render_managed_runtime_path(path),
            error
        )
    })
}

/// Return whether an environment marker matches the expected marker exactly.
/// 返回某个环境标记是否与期望标记完全匹配。
pub fn managed_env_marker_matches(
    actual: &ManagedRuntimeEnvMarker,
    expected: &ManagedRuntimeEnvMarker,
) -> bool {
    actual == expected
}

/// Ensure one managed runtime environment exists and matches its expected marker.
/// 确保一个受管运行时环境存在并且匹配其期望标记。
pub fn ensure_managed_env(plan: &ManagedRuntimeEnvPlan) -> Result<(), String> {
    validate_managed_runtime_plan_assets(plan)?;
    if managed_env_is_ready(plan)? {
        return Ok(());
    }
    // Per-environment construction lock shared by every engine in this process.
    // 当前进程中所有引擎共享的每环境构建锁。
    let build_lock = managed_runtime_env_lock(&plan.env_dir);
    // Build guard recovered after poisoning so a failed installer does not permanently wedge retries.
    // 在锁中毒后恢复构建保护，避免失败安装永久阻塞重试。
    let _build_guard = build_lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    // Cross-process lock prevents another host process from staging or replacing the same env.
    // 跨进程锁防止另一个宿主进程同时暂存或替换同一个环境。
    let _file_lock = acquire_managed_runtime_env_file_lock(plan)?;
    // Double-check under the construction lock because another caller may have published the environment.
    // 在构建锁内二次检查，因为其他调用方可能已经发布环境。
    if managed_env_is_ready(plan)? {
        return Ok(());
    }
    match plan.runtime {
        ManagedRuntimeKind::Python => create_python_env(plan),
        ManagedRuntimeKind::Node => create_node_env(plan),
    }
}

/// Return whether a managed runtime environment already matches its expected marker.
/// 返回一个受管运行时环境是否已经匹配其期望标记。
pub fn managed_env_is_ready(plan: &ManagedRuntimeEnvPlan) -> Result<bool, String> {
    // Environment directory itself is validated without following links before its marker is read.
    // 在读取 marker 前先以不跟随链接的方式校验环境目录本身。
    if !managed_runtime_directory_path_is_directory(
        &plan.env_dir,
        "managed runtime environment directory",
    )? {
        return Ok(false);
    }
    let marker_path = managed_env_marker_path(&plan.env_dir);
    if !managed_env_marker_path_is_file(&marker_path)? {
        return Ok(false);
    }
    let actual = read_managed_env_marker(&marker_path)?;
    Ok(managed_env_marker_matches(&actual, &plan.expected_marker))
}

/// Revalidate the roots and exact runtime assets captured by an environment plan.
/// 重新校验环境计划捕获的根集合与精确运行时资产。
///
/// `plan` contains the immutable engine root authority, canonical installation paths, manifest
/// identities, and executable identities that must remain unchanged before any environment use.
/// `plan` 包含不可变引擎根授权、规范安装路径、清单身份及可执行文件身份；任何环境使用前这些
/// 内容都必须保持不变。
///
/// Returns unit only when both runtime and package-manager installations still resolve to the exact
/// captured paths and hashes; otherwise returns an explicit source-qualified identity error.
/// 仅当运行时与包管理器安装仍解析到精确捕获路径及哈希时返回空值，否则返回带来源的显式身份错误。
pub(crate) fn validate_managed_runtime_plan_assets(
    plan: &ManagedRuntimeEnvPlan,
) -> Result<(), String> {
    plan.managed_runtime_roots
        .validate_live_filesystem_identity()?;
    if plan.runtime_root != plan.managed_runtime_roots.runtime_root()
        || plan.distribution_root != plan.managed_runtime_roots.distribution_root()
        || plan.environment_root != plan.managed_runtime_roots.environment_root()
        || plan.distribution_source != plan.managed_runtime_roots.distribution_source()
        || plan.environment_source != plan.managed_runtime_roots.environment_source()
    {
        return Err("managed runtime plan root authority changed".to_string());
    }
    if plan.env_dir == plan.environment_root || !plan.env_dir.starts_with(&plan.environment_root) {
        return Err(format!(
            "managed runtime environment source={} produced an env directory outside its root: {}",
            plan.environment_source.as_str(),
            render_managed_runtime_path(&plan.env_dir)
        ));
    }
    // RuntimeIdentity re-resolves the exact selected interpreter without any ambient fallback.
    // RuntimeIdentity 在不使用任何环境回退的前提下重新解析所选精确解释器。
    let runtime_identity = resolve_managed_runtime_install_identity(
        &plan.distribution_root,
        &plan.runtime_install_root,
        plan.runtime.as_str(),
        &plan.runtime_version,
        &plan.platform,
    )
    .map_err(|error| {
        format!(
            "managed runtime distribution source={}: {error}",
            plan.distribution_source.as_str()
        )
    })?;
    validate_managed_runtime_install_identity_matches(
        "runtime",
        &runtime_identity,
        &plan.runtime_install_root,
        &plan.runtime_executable,
        &plan.runtime_install_manifest_hash,
        &plan.runtime_executable_hash,
    )?;
    // PackageManagerPlatform follows the stable cross-platform `any` contract used only by pnpm.
    // PackageManagerPlatform 仅对 pnpm 使用稳定的跨平台 `any` 契约。
    let package_manager_platform = if plan.package_manager == "pnpm" {
        "any"
    } else {
        plan.platform.as_str()
    };
    let package_manager_identity = resolve_managed_runtime_install_identity(
        &plan.distribution_root,
        &plan.package_manager_install_root,
        &plan.package_manager,
        &plan.package_manager_version,
        package_manager_platform,
    )
    .map_err(|error| {
        format!(
            "managed runtime distribution source={}: {error}",
            plan.distribution_source.as_str()
        )
    })?;
    validate_managed_runtime_install_identity_matches(
        "package manager",
        &package_manager_identity,
        &plan.package_manager_install_root,
        &plan.package_manager_executable,
        &plan.package_manager_install_manifest_hash,
        &plan.package_manager_executable_hash,
    )
}

/// Compare one freshly resolved installation identity with the exact plan-time identity.
/// 将单个最新解析安装身份与精确计划时身份进行比较。
///
/// `label` identifies the asset in diagnostics; the remaining expected values are immutable plan
/// fields compared against `actual` without accepting alternate paths or hashes.
/// `label` 在诊断中标识资产；其余期望值均为不可变计划字段，并与 `actual` 比较且不接受替代路径或哈希。
///
/// Returns unit on an exact match or an explicit changed-identity error.
/// 精确匹配时返回空值，否则返回显式身份已变更错误。
fn validate_managed_runtime_install_identity_matches(
    label: &str,
    actual: &ManagedRuntimeInstallIdentity,
    expected_install_root: &Path,
    expected_executable: &Path,
    expected_manifest_hash: &str,
    expected_executable_hash: &str,
) -> Result<(), String> {
    if actual.install_root != expected_install_root
        || actual.executable != expected_executable
        || actual.manifest_hash != expected_manifest_hash
        || actual.executable_hash != expected_executable_hash
    {
        return Err(format!(
            "managed runtime {label} installation identity changed"
        ));
    }
    Ok(())
}

/// Create one Python virtual environment and synchronize it from the lockfile.
/// 创建一个 Python 虚拟环境并按锁文件同步依赖。
///
/// `plan` supplies canonical managed runtime/package-manager executables, lockfile identity, and
/// the unpublished-to-published environment destination.
/// `plan` 提供规范受管运行时与包管理器可执行文件、锁文件身份及从未发布到已发布的环境目标。
///
/// Returns unit after atomic publication, or a cleanup-complete build/command error.
/// 原子发布后返回空值；失败时返回已完成清理的构建或命令错误。
fn create_python_env(plan: &ManagedRuntimeEnvPlan) -> Result<(), String> {
    validate_managed_runtime_plan_assets(plan)?;
    // Unique unpublished same-parent directory used for the complete isolated uv build.
    // 完整隔离 uv 构建使用的唯一同父级未发布目录。
    let build_dir = prepare_build_dir(plan)?;
    // Build result retained so every failure removes only the unpublished directory.
    // 保留构建结果，使每次失败都只删除未发布目录。
    let build_result = (|| {
        // Private lockfile copy is verified before uv can consume it, closing the plan/build race.
        // 在 uv 消费前校验私有锁文件副本，关闭计划与构建之间的竞态窗口。
        let build_lockfile = build_dir.join("requirements.lock");
        fs::copy(&plan.lockfile_path, &build_lockfile).map_err(|error| {
            format!(
                "Failed to copy {} into {}: {}",
                render_managed_runtime_path(&plan.lockfile_path),
                render_managed_runtime_path(&build_lockfile),
                error
            )
        })?;
        verify_managed_runtime_build_input_hash(
            &build_lockfile,
            &plan.lock_hash,
            "Python lockfile",
        )?;
        // Virtual environment created wholly inside the unpublished build directory.
        // 完全在未发布构建目录内创建的虚拟环境。
        let venv_dir = build_dir.join(".venv");
        // First uv command whose environment contains only managed executable locations.
        // 首个 uv 命令，其环境仅包含受管可执行文件位置。
        let mut create_command = Command::new(&plan.package_manager_executable);
        create_command
            .arg("venv")
            .arg("--python")
            .arg(host_process_path_argument(&plan.runtime_executable))
            .arg(host_process_path_argument(&venv_dir))
            .current_dir(host_process_path_argument(&build_dir));
        configure_managed_command_base_environment(
            &mut create_command,
            &build_dir,
            &[
                managed_executable_parent(&plan.package_manager_executable)?.to_path_buf(),
                managed_executable_parent(&plan.runtime_executable)?.to_path_buf(),
            ],
        )?;
        // uv must not discover user or system configuration outside the managed build.
        // uv 不得发现受管构建目录之外的用户或系统配置。
        create_command.env("UV_NO_CONFIG", "1");
        run_command(
            &mut create_command,
            "create managed Python virtual environment",
        )?;
        // Environment interpreter used by the reproducible lockfile synchronization step.
        // 可复现锁文件同步步骤使用的环境解释器。
        let python_executable = python_venv_executable(&venv_dir);
        // Second uv command isolated from host credentials and startup overrides.
        // 与宿主凭据及启动覆盖隔离的第二个 uv 命令。
        let mut sync_command = Command::new(&plan.package_manager_executable);
        sync_command
            .arg("pip")
            .arg("sync")
            .arg(host_process_path_argument(&build_lockfile))
            .arg("--python")
            .arg(host_process_path_argument(&python_executable))
            .arg("--cache-dir")
            .arg(host_process_path_argument(&package_store_dir_for_plan(
                plan,
            )))
            .current_dir(host_process_path_argument(&build_dir));
        configure_managed_command_base_environment(
            &mut sync_command,
            &build_dir,
            &[
                managed_executable_parent(&plan.package_manager_executable)?.to_path_buf(),
                managed_executable_parent(&python_executable)?.to_path_buf(),
                managed_executable_parent(&plan.runtime_executable)?.to_path_buf(),
            ],
        )?;
        sync_command.env("UV_NO_CONFIG", "1");
        run_command(&mut sync_command, "synchronize managed Python environment")?;
        finish_build_dir(plan, build_dir.clone())
    })();
    cleanup_unpublished_build_after_result(&build_dir, build_result)
}

/// Create one Node dependency environment and install dependencies from the lockfile.
/// 创建一个 Node 依赖环境并按锁文件安装依赖。
///
/// `plan` supplies canonical Node/pnpm executables, package inputs, lockfile identity, and the
/// unpublished-to-published environment destination.
/// `plan` 提供规范 Node/pnpm 可执行文件、包输入、锁文件身份及从未发布到已发布的环境目标。
///
/// Returns unit after atomic publication, or a cleanup-complete copy/install error.
/// 原子发布后返回空值；失败时返回已完成清理的复制或安装错误。
fn create_node_env(plan: &ManagedRuntimeEnvPlan) -> Result<(), String> {
    validate_managed_runtime_plan_assets(plan)?;
    // Unpublished same-parent build directory used for the entire pnpm installation.
    // 整个 pnpm 安装期间使用的同父级未发布构建目录。
    let build_dir = prepare_build_dir(plan)?;
    // Required package manifest declared by the authoritative package context.
    // 由权威包上下文声明的必需 package 清单。
    let package_json = plan.package_manifest_path.as_ref().ok_or_else(|| {
        "node package_json is required to create a managed Node environment".to_string()
    })?;
    // Installation result retained so every failure removes only the unpublished build directory.
    // 保留安装结果，使每次失败都只删除未发布构建目录。
    let build_package_json = build_dir.join("package.json");
    let build_lockfile = build_dir.join("pnpm-lock.yaml");
    let install_result = fs::copy(package_json, &build_package_json)
        .map_err(|error| {
            format!(
                "Failed to copy {} into {}: {}",
                render_managed_runtime_path(package_json),
                render_managed_runtime_path(&build_dir),
                error
            )
        })
        .and_then(|_| {
            fs::copy(&plan.lockfile_path, &build_lockfile).map_err(|error| {
                format!(
                    "Failed to copy {} into {}: {}",
                    render_managed_runtime_path(&plan.lockfile_path),
                    render_managed_runtime_path(&build_dir),
                    error
                )
            })
        })
        .and_then(|_| {
            let expected_package_hash = plan.package_manifest_hash.as_deref().ok_or_else(|| {
                "node package_json hash is unavailable during environment creation".to_string()
            })?;
            // Both private inputs are verified before pnpm opens either build-directory name.
            // 在 pnpm 打开任一构建目录名称前校验两个私有输入。
            verify_managed_runtime_build_input_hash(
                &build_package_json,
                expected_package_hash,
                "Node package manifest",
            )?;
            verify_managed_runtime_build_input_hash(
                &build_lockfile,
                &plan.lock_hash,
                "Node lockfile",
            )
        })
        .and_then(|_| {
            // pnpm command launched through the exact managed Node executable.
            // 通过精确受管 Node 可执行文件启动的 pnpm 命令。
            let mut install_command = Command::new(&plan.runtime_executable);
            install_command
                .arg(host_process_path_argument(&plan.package_manager_executable))
                .arg("install")
                .arg("--frozen-lockfile")
                // Hoisted installs avoid Windows absolute junctions that would retain the unpublished
                // build-directory name after atomic publication.
                // Hoisted 安装可避免 Windows 绝对目录联接在原子发布后仍指向未发布构建目录名。
                .arg("--node-linker")
                .arg("hoisted")
                .arg("--store-dir")
                .arg(host_process_path_argument(&package_store_dir_for_plan(
                    plan,
                )))
                .current_dir(host_process_path_argument(&build_dir));
            configure_managed_command_base_environment(
                &mut install_command,
                &build_dir,
                &[
                    managed_executable_parent(&plan.runtime_executable)?.to_path_buf(),
                    managed_executable_parent(&plan.package_manager_executable)?.to_path_buf(),
                    build_dir.join("node_modules").join(".bin"),
                ],
            )?;
            // pnpm home is kept inside the unpublished managed environment.
            // pnpm 主目录保存在未发布受管环境内部。
            install_command.env(
                "PNPM_HOME",
                host_process_path_argument(managed_executable_parent(
                    &plan.package_manager_executable,
                )?),
            );
            run_command(&mut install_command, "install managed Node environment")
        })
        .and_then(|()| finish_build_dir(plan, build_dir.clone()));
    cleanup_unpublished_build_after_result(&build_dir, install_result)
}

/// Preserve one build result while removing a failed unpublished environment with full diagnostics.
/// 保留单次构建结果，并在失败时删除未发布环境且提供完整诊断。
///
/// `build_dir` is the exact atomically created unpublished directory; `result` is its build outcome.
/// `build_dir` 是原子创建的精确未发布目录；`result` 是其构建结果。
///
/// Returns success unchanged or the primary failure augmented with any cleanup failure.
/// 原样返回成功结果；失败时附加任何清理失败信息。
fn cleanup_unpublished_build_after_result(
    build_dir: &Path,
    result: Result<(), String>,
) -> Result<(), String> {
    let Err(primary_error) = result else {
        return Ok(());
    };
    match fs::remove_dir_all(build_dir) {
        Ok(()) => Err(primary_error),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Err(primary_error),
        Err(cleanup_error) => Err(format!(
            "{primary_error}; failed to remove unpublished managed environment {}: {cleanup_error}",
            render_managed_runtime_path(build_dir)
        )),
    }
}

/// Prepare one clean temporary build directory next to the target environment.
/// 在目标环境旁准备一个干净的临时构建目录。
fn prepare_build_dir(plan: &ManagedRuntimeEnvPlan) -> Result<PathBuf, String> {
    prepare_build_dir_with_sequence(plan, allocate_managed_runtime_build_sequence)
}

/// Prepare one unpublished build directory with an injected nonwrapping sequence allocator.
/// 使用注入的不可回绕序号分配器准备一个未发布构建目录。
///
/// `plan` supplies the exact same-parent environment identity and `allocate_sequence` supplies
/// collision-resistant candidate suffixes without hiding allocation exhaustion.
/// `plan` 提供精确的同父级环境身份，`allocate_sequence` 提供抗碰撞候选后缀且不会掩盖分配耗尽。
///
/// Returns one atomically created directory or a deterministic filesystem/allocation error.
/// 返回一个原子创建的目录，或确定性的文件系统/分配错误。
fn prepare_build_dir_with_sequence<F>(
    plan: &ManagedRuntimeEnvPlan,
    mut allocate_sequence: F,
) -> Result<PathBuf, String>
where
    F: FnMut() -> Result<u64, String>,
{
    // Existing parent that owns both unpublished and final environment directories.
    // 同时拥有未发布与最终环境目录的既有父目录。
    let parent = plan.env_dir.parent().ok_or_else(|| {
        format!(
            "managed env directory has no parent: {}",
            render_managed_runtime_path(&plan.env_dir)
        )
    })?;
    fs::create_dir_all(parent).map_err(|error| {
        format!(
            "Failed to create {}: {}",
            render_managed_runtime_path(parent),
            error
        )
    })?;
    // Atomically created same-parent directory tolerating stale PID-reuse crash remnants.
    // 原子创建的同父级目录，可容忍 PID 复用产生的崩溃残留。
    for _attempt in 0..MAX_MANAGED_RUNTIME_BUILD_DIR_ATTEMPTS {
        // Nonwrapping process-local sequence combined with the process id for cross-process isolation.
        // 与进程 id 组合用于跨进程隔离的不可回绕进程内序号。
        let sequence = allocate_sequence()?;
        // Same-parent unpublished candidate so final publication uses one filesystem rename.
        // 与最终目录同父级的未发布候选，使最终发布使用一次文件系统重命名。
        let build_dir = parent.join(format!(
            ".building-{}-{}-{sequence}",
            plan.env_hash,
            std::process::id()
        ));
        match fs::create_dir(&build_dir) {
            Ok(()) => return Ok(build_dir),
            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
            Err(error) => {
                return Err(format!(
                    "Failed to create {}: {}",
                    render_managed_runtime_path(&build_dir),
                    error
                ));
            }
        }
    }
    Err(format!(
        "failed to allocate managed runtime build directory after {MAX_MANAGED_RUNTIME_BUILD_DIR_ATTEMPTS} attempts"
    ))
}

/// Finalize one temporary build directory into its stable environment directory.
/// 将一个临时构建目录收尾成稳定环境目录。
fn finish_build_dir(plan: &ManagedRuntimeEnvPlan, build_dir: PathBuf) -> Result<(), String> {
    finish_build_dir_with_backup_remover(
        plan,
        build_dir,
        remove_identity_bound_managed_runtime_backup,
    )
}

/// Finalize one build with an injectable immediate obsolete-backup remover.
/// 使用可注入的即时过时备份删除器收尾单个构建。
///
/// `plan` and `build_dir` define the publication transaction; `remove_backup` is invoked only after
/// the new environment name commits and allows deterministic retry-handoff tests.
/// `plan` 与 `build_dir` 定义发布事务；`remove_backup` 仅在新环境名称提交后调用，并支持确定性
/// 重试交接测试。
///
/// Returns success once publication commits, even when obsolete-backup deletion is retained for
/// durable retry. Pre-commit failures remain explicit errors.
/// 发布一旦提交即返回成功，即使过时备份删除已交给持久重试；提交前失败仍返回显式错误。
fn finish_build_dir_with_backup_remover<F>(
    plan: &ManagedRuntimeEnvPlan,
    build_dir: PathBuf,
    remove_backup: F,
) -> Result<(), String>
where
    F: FnOnce(&Path, &ManagedFilesystemObjectIdentity) -> Result<(), String>,
{
    write_expected_marker(&build_dir, &plan.expected_marker)?;
    // PublishLease is acquired before the first probe or mutation of the published environment.
    // PublishLease 会在首次探测或修改已发布环境之前获取。
    let _publish_lease = try_acquire_managed_runtime_env_publish_lease(plan)?;
    // Optional same-parent backup retaining the previously published environment during replacement.
    // 替换期间保留此前已发布环境的可选同父级备份。
    let mut backup =
        if managed_runtime_directory_path_is_directory(&plan.env_dir, "managed env directory")? {
            // Native identity captured before rename remains bound to the same directory object.
            // rename 前捕获的平台原生身份会继续绑定同一个目录对象。
            let identity =
                capture_managed_directory_identity(&plan.env_dir, "published managed environment")?;
            // Recovery capacity is guaranteed before the old published name is moved.
            // 在移动旧已发布名称前保证恢复容量。
            let (recovery_center, recovery_permit) =
                reserve_managed_runtime_backup_recovery_slot()?;
            // Unique backup path that cannot collide with another process-local replacement.
            // 不会与其他进程内替换发生碰撞的唯一备份路径。
            let sequence = allocate_managed_runtime_build_sequence()?;
            let parent = plan.env_dir.parent().ok_or_else(|| {
                format!(
                    "managed env directory has no parent: {}",
                    render_managed_runtime_path(&plan.env_dir)
                )
            })?;
            // Canonical parent makes the retained backup path stable across Windows verbatim names.
            // 规范父目录使保留备份路径在 Windows 逐字名称下保持稳定。
            let canonical_parent = fs::canonicalize(parent).map_err(|error| {
                format!(
                    "failed to canonicalize managed environment parent {}: {error}",
                    render_managed_runtime_path(parent)
                )
            })?;
            let backup = canonical_parent.join(format!(
                ".replaced-{}-{}-{sequence}",
                plan.env_hash,
                std::process::id()
            ));
            fs::rename(&plan.env_dir, &backup).map_err(|error| {
                format!(
                    "Failed to stage existing environment {} as {}: {}",
                    render_managed_runtime_path(&plan.env_dir),
                    render_managed_runtime_path(&backup),
                    error
                )
            })?;
            Some((backup, identity, recovery_center, recovery_permit))
        } else {
            None
        };
    // Single same-filesystem rename publishes only a complete environment.
    // 单次同文件系统重命名只发布完整环境。
    if let Err(publish_error) = fs::rename(&build_dir, &plan.env_dir) {
        if let Some((backup_path, _, _, _)) = backup.as_ref() {
            // Immediate rollback is attempted while construction and publication locks remain held.
            // 在构建锁与发布锁仍被持有时尝试即时回滚。
            if let Err(rollback_error) = fs::rename(backup_path, &plan.env_dir) {
                let (backup_path, identity, recovery_center, recovery_permit) = backup
                    .take()
                    .expect("present managed environment backup must remain owned");
                recovery_center.enqueue(ManagedRuntimeBackupRecoveryRecord {
                    backup_path,
                    identity,
                    action: ManagedRuntimeBackupRecoveryAction::RestoreFailedPublication {
                        plan: Box::new(plan.clone()),
                    },
                    _permit: recovery_permit,
                    error_reported: false,
                });
                return Err(format!(
                    "Failed to publish {} as {}: {}; rollback also failed and was scheduled for persistent recovery: {}",
                    render_managed_runtime_path(&build_dir),
                    render_managed_runtime_path(&plan.env_dir),
                    publish_error,
                    rollback_error
                ));
            }
            // Successful rollback leaves no backup path and releases the unused reservation.
            // 成功回滚不会留下备份路径，并释放未使用预留。
            drop(backup.take());
        }
        return Err(format!(
            "Failed to publish {} as {}: {}",
            render_managed_runtime_path(&build_dir),
            render_managed_runtime_path(&plan.env_dir),
            publish_error
        ));
    }
    if let Some((backup_path, identity, recovery_center, recovery_permit)) = backup.take() {
        // ImmediateCleanup is isolated so a panic cannot discard the only retained backup owner.
        // 隔离即时清理调用，确保 panic 不会丢弃唯一保留的备份所有者。
        let immediate_cleanup = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            remove_backup(&backup_path, &identity)
        }));
        // RecoveryRecord receives ownership for every non-successful immediate cleanup outcome.
        // 每一种未成功的即时清理结果都会把所有权移交给恢复记录。
        let recovery_error = match immediate_cleanup {
            Ok(Ok(())) => None,
            Ok(Err(error)) => Some(error),
            Err(_) => Some("obsolete-backup cleanup panicked".to_string()),
        };
        if let Some(error) = recovery_error {
            crate::runtime_logging::warn(format!(
                "[LuaSkill:warn] managed environment publication committed; obsolete backup cleanup was scheduled for retry: {error}"
            ));
            recovery_center.enqueue(ManagedRuntimeBackupRecoveryRecord {
                backup_path,
                identity,
                action: ManagedRuntimeBackupRecoveryAction::RemoveCommittedBackup,
                _permit: recovery_permit,
                error_reported: true,
            });
        }
    }
    Ok(())
}

/// Write the expected marker into one environment directory.
/// 将期望标记写入一个环境目录。
fn write_expected_marker(env_dir: &Path, marker: &ManagedRuntimeEnvMarker) -> Result<(), String> {
    let marker_path = managed_env_marker_path(env_dir);
    let text = serde_json::to_string_pretty(marker)
        .map_err(|error| format!("Failed to serialize managed env marker: {}", error))?;
    fs::write(&marker_path, format!("{}\n", text)).map_err(|error| {
        format!(
            "Failed to write {}: {}",
            render_managed_runtime_path(&marker_path),
            error
        )
    })
}

/// Run one process command and convert failures into stable error text.
/// 运行一个进程命令并将失败转换为稳定错误文本。
fn run_command(command: &mut Command, operation: &str) -> Result<(), String> {
    let output = command
        .output()
        .map_err(|error| format!("Failed to {}: {}", operation, error))?;
    if output.status.success() {
        return Ok(());
    }
    let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
    Err(format!(
        "Failed to {}: status={} stdout={} stderr={}",
        operation, output.status, stdout, stderr
    ))
}

/// Return the Python executable inside one venv directory.
/// 返回单个 venv 目录中的 Python 可执行文件。
fn python_venv_executable(venv_dir: &Path) -> PathBuf {
    if cfg!(windows) {
        venv_dir.join("Scripts").join("python.exe")
    } else {
        venv_dir.join("bin").join("python")
    }
}

/// Return the package-store directory used by one environment plan.
/// 返回单个环境计划使用的包存储目录。
fn package_store_dir_for_plan(plan: &ManagedRuntimeEnvPlan) -> PathBuf {
    let family = match plan.runtime {
        ManagedRuntimeKind::Python => "python",
        ManagedRuntimeKind::Node => "node",
    };
    let store_name = match plan.runtime {
        ManagedRuntimeKind::Python => "uv-cache",
        ManagedRuntimeKind::Node => "pnpm-store",
    };
    plan.runtime_root
        .join("dependencies")
        .join("package_store")
        .join(family)
        .join(store_name)
}

/// Return the parent directory of one validated managed executable.
/// 返回一个已验证受管可执行文件的父目录。
///
/// `executable` is an absolute canonical runtime or package-manager executable path.
/// `executable` 是运行时或包管理器可执行文件的绝对规范路径。
///
/// Returns the parent directory or an explicit structural error.
/// 返回父目录，或显式的结构错误。
fn managed_executable_parent(executable: &Path) -> Result<&Path, String> {
    executable.parent().ok_or_else(|| {
        format!(
            "managed executable has no parent directory: {}",
            render_managed_runtime_path(executable)
        )
    })
}

/// Replace one command's inherited environment with the minimal managed-runtime baseline.
/// 使用最小受管运行时基线替换单个命令继承的环境。
///
/// `command` is the not-yet-spawned child command, `controlled_home` is its isolated writable
/// home/temp root, and `path_entries` are the only executable-search directories it may receive.
/// `command` 是尚未启动的子命令，`controlled_home` 是其隔离可写 home/temp 根，
/// `path_entries` 是它可以接收的唯一可执行文件搜索目录。
///
/// Returns unit after installing the controlled environment, or an explicit path/platform error.
/// 安装受控环境后返回空值；路径或平台异常时返回显式错误。
pub(crate) fn configure_managed_command_base_environment(
    command: &mut Command,
    controlled_home: &Path,
    path_entries: &[PathBuf],
) -> Result<(), String> {
    if !controlled_home.is_absolute() {
        return Err(format!(
            "managed command home is not absolute: {}",
            render_managed_runtime_path(controlled_home)
        ));
    }
    if path_entries.is_empty() {
        return Err("managed command PATH requires at least one controlled directory".to_string());
    }
    for directory in path_entries {
        if !directory.is_absolute() {
            return Err(format!(
                "managed command PATH entry is not absolute: {}",
                render_managed_runtime_path(directory)
            ));
        }
    }
    // Clearing first is the security boundary: proxy credentials, cloud tokens, startup hooks,
    // loader overrides, and every other host variable stay unavailable to package processes.
    // 首先清空是安全边界：代理凭据、云令牌、启动钩子、加载器覆盖及其他全部宿主变量均不会暴露给包进程。
    command.env_clear();
    // ChildHome uses the equivalent non-verbatim spelling accepted by Node.js 24 path parsers.
    // ChildHome 使用 Node.js 24 路径解析器可接受的等价非 verbatim 写法。
    let child_home = host_process_path_argument(controlled_home);
    command.env("HOME", &child_home);
    command.env("TMPDIR", &child_home);
    // Platform-native PATH assembled exclusively from caller-authorized managed directories.
    // 仅根据调用方授权受管目录组装的平台原生 PATH。
    // ChildPathEntries keep the validated directories while removing only Windows verbatim syntax.
    // ChildPathEntries 保留已校验目录，仅移除 Windows verbatim 语法。
    let child_path_entries = path_entries
        .iter()
        .map(|path| host_process_path_argument(path))
        .collect::<Vec<_>>();
    let joined_path = env::join_paths(child_path_entries.iter())
        .map_err(|error| format!("failed to construct controlled managed-runtime PATH: {error}"))?;
    command.env("PATH", joined_path);
    #[cfg(windows)]
    install_required_windows_command_environment(command, &child_home)?;
    Ok(())
}

/// Restore only validated Windows process-bootstrap variables after `env_clear`.
/// 在 `env_clear` 后仅恢复经过验证的 Windows 进程启动变量。
///
/// `command` receives the required SystemRoot/ComSpec contract and `controlled_home` replaces all
/// user-profile and temporary directories so no host-user paths or credentials are inherited.
/// `command` 接收必需的 SystemRoot/ComSpec 契约，`controlled_home` 替换全部用户配置与临时目录，
/// 从而不继承宿主用户路径或凭据。
///
/// Returns unit or an explicit validation error for an unusable Windows bootstrap environment.
/// 返回空值；Windows 启动环境不可用时返回显式校验错误。
#[cfg(windows)]
fn install_required_windows_command_environment(
    command: &mut Command,
    controlled_home: &Path,
) -> Result<(), String> {
    // SystemRoot is the sole trusted root for the command interpreter required by Windows tools.
    // SystemRoot 是 Windows 工具所需命令解释器的唯一可信根。
    let system_root = env::var_os("SystemRoot")
        .ok_or_else(|| "required Windows environment variable SystemRoot is missing".to_string())?;
    if !Path::new(&system_root).is_absolute() {
        return Err(format!(
            "Windows SystemRoot is not absolute: {}",
            render_managed_runtime_path(Path::new(&system_root))
        ));
    }
    // Canonical root used only for validation; children receive the native non-verbatim value.
    // 仅用于校验的规范根；子进程接收原生非逐字路径值。
    let canonical_system_root = fs::canonicalize(&system_root).map_err(|error| {
        format!(
            "failed to canonicalize Windows SystemRoot {}: {error}",
            render_managed_runtime_path(Path::new(&system_root))
        )
    })?;
    if !canonical_system_root.is_dir() {
        return Err(format!(
            "Windows SystemRoot is not a directory: {}",
            render_managed_runtime_path(&canonical_system_root)
        ));
    }
    // ComSpec is canonicalized and constrained to SystemRoot to prevent executable injection.
    // 对 ComSpec 进行规范化并限制在 SystemRoot 内，以防止可执行文件注入。
    let com_spec = env::var_os("ComSpec")
        .ok_or_else(|| "required Windows environment variable ComSpec is missing".to_string())?;
    if !Path::new(&com_spec).is_absolute() {
        return Err(format!(
            "Windows ComSpec is not absolute: {}",
            render_managed_runtime_path(Path::new(&com_spec))
        ));
    }
    // Canonical interpreter used only to prove type and SystemRoot containment.
    // 仅用于证明类型及 SystemRoot 包含关系的规范解释器。
    let canonical_com_spec = fs::canonicalize(&com_spec).map_err(|error| {
        format!(
            "failed to canonicalize Windows ComSpec {}: {error}",
            render_managed_runtime_path(Path::new(&com_spec))
        )
    })?;
    if canonical_com_spec == canonical_system_root
        || !canonical_com_spec.starts_with(&canonical_system_root)
        || !canonical_com_spec.is_file()
    {
        return Err(format!(
            "Windows ComSpec is not a regular file strictly inside SystemRoot: {}",
            render_managed_runtime_path(&canonical_com_spec)
        ));
    }
    // Child bootstrap paths retain the validated identities without Windows verbatim syntax.
    // 子进程启动路径保留已校验身份，同时移除 Windows verbatim 语法。
    let child_system_root = PathBuf::from(
        normalize_host_input_path_text(&system_root.to_string_lossy())
            .map_err(|error| format!("SystemRoot: {error}"))?,
    );
    let child_com_spec = PathBuf::from(
        normalize_host_input_path_text(&com_spec.to_string_lossy())
            .map_err(|error| format!("ComSpec: {error}"))?,
    );
    command.env("SystemRoot", &child_system_root);
    command.env("WINDIR", &child_system_root);
    command.env("ComSpec", &child_com_spec);
    command.env("PATHEXT", ".COM;.EXE;.BAT;.CMD");
    // Optional non-secret drive bootstrap value used by Windows command scripts.
    // Windows 命令脚本使用的可选非密钥驱动器启动值。
    if let Some(system_drive) = env::var_os("SystemDrive") {
        // Lua/Node-compatible drive value rejected if it names another verbatim namespace.
        // 与 Lua/Node 兼容的驱动器值；若它指向其他 verbatim 命名空间则拒绝。
        let child_system_drive = normalize_host_input_path_text(&system_drive.to_string_lossy())
            .map_err(|error| format!("SystemDrive: {error}"))?;
        command.env("SystemDrive", child_system_drive);
    }
    command.env("USERPROFILE", controlled_home);
    command.env("APPDATA", controlled_home);
    command.env("LOCALAPPDATA", controlled_home);
    command.env("TEMP", controlled_home);
    command.env("TMP", controlled_home);
    Ok(())
}

/// Recursively copy one directory tree.
/// 递归复制一个目录树。
#[cfg(test)]
fn copy_dir_recursive(source: &Path, destination: &Path) -> Result<(), String> {
    fs::create_dir_all(destination).map_err(|error| {
        format!(
            "Failed to create {}: {}",
            render_managed_runtime_path(destination),
            error
        )
    })?;
    for entry in fs::read_dir(source).map_err(|error| {
        format!(
            "Failed to read {}: {}",
            render_managed_runtime_path(source),
            error
        )
    })? {
        let entry = entry.map_err(|error| {
            format!(
                "Failed to read directory entry under {}: {}",
                render_managed_runtime_path(source),
                error
            )
        })?;
        let source_path = entry.path();
        let destination_path = destination.join(entry.file_name());
        // Entry type read from the directory iterator without following symlinks.
        // 从目录迭代器读取且不跟随符号链接的目录项类型。
        let file_type = entry.file_type().map_err(|error| {
            format!(
                "Failed to inspect {} under {}: {}",
                render_managed_runtime_path(&source_path),
                render_managed_runtime_path(source),
                error
            )
        })?;
        if file_type.is_dir() {
            copy_dir_recursive(&source_path, &destination_path)?;
        } else if file_type.is_file() {
            fs::copy(&source_path, &destination_path).map_err(|error| {
                format!(
                    "Failed to copy {} to {}: {}",
                    render_managed_runtime_path(&source_path),
                    render_managed_runtime_path(&destination_path),
                    error
                )
            })?;
        } else {
            return Err(format!(
                "Failed to copy {} to {}: unsupported file type",
                render_managed_runtime_path(&source_path),
                render_managed_runtime_path(&destination_path)
            ));
        }
    }
    Ok(())
}

/// Resolve one Python managed runtime environment plan from a skill declaration.
/// 根据 skill 声明解析一个 Python 受管运行时环境计划。
pub(crate) fn resolve_python_env_plan(
    package: &ManagedRuntimePackageContext,
    spec: &PythonRuntimeDependencySpec,
) -> Result<ManagedRuntimeEnvPlan, String> {
    validate_managed_runtime_resolver_version(&spec.version)?;
    validate_managed_runtime_resolver_version(&spec.package_manager_version)?;
    // ManagedRuntimeRoots is the single engine-selected authority for all three root roles.
    // ManagedRuntimeRoots 是三个根角色唯一的引擎选定授权。
    let managed_runtime_roots = package.managed_runtime_roots();
    managed_runtime_roots.validate_live_filesystem_identity()?;
    let platform = current_managed_runtime_platform_key()?;
    let runtime_dir = runtime_install_dir(
        managed_runtime_roots.distribution_root(),
        "python",
        &format!("cpython-{}-{}", spec.version, platform),
    );
    let runtime_install = resolve_managed_runtime_install_identity(
        managed_runtime_roots.distribution_root(),
        &runtime_dir,
        "python",
        &spec.version,
        &platform,
    )
    .map_err(|error| {
        format!(
            "managed runtime distribution source={}: {error}",
            managed_runtime_roots.distribution_source().as_str()
        )
    })?;
    let package_manager = spec.package_manager.as_managed_runtime_str().to_string();
    let package_manager_install_dir = runtime_install_dir(
        managed_runtime_roots.distribution_root(),
        "python",
        &format!("uv-{}-{}", spec.package_manager_version, platform),
    );
    let package_manager_install = resolve_managed_runtime_install_identity(
        managed_runtime_roots.distribution_root(),
        &package_manager_install_dir,
        "uv",
        &spec.package_manager_version,
        &platform,
    )
    .map_err(|error| {
        format!(
            "managed runtime distribution source={}: {error}",
            managed_runtime_roots.distribution_source().as_str()
        )
    })?;
    // Canonical lockfile constrained to the trusted package root.
    // 限制在可信包根内的规范锁文件。
    let lockfile_path = package.resolve_existing_file(&spec.lockfile, "python_runtime.lockfile")?;
    let lock_hash = sha256_file(&lockfile_path)?;
    let hash_input = ManagedRuntimeEnvHashInput {
        runtime: ManagedRuntimeKind::Python,
        runtime_version: spec.version.clone(),
        platform,
        package_manager,
        package_manager_version: spec.package_manager_version.clone(),
        lock_hash,
        package_manifest_hash: None,
        runtime_install_manifest_hash: runtime_install.manifest_hash.clone(),
        runtime_executable_hash: runtime_install.executable_hash.clone(),
        package_manager_install_manifest_hash: package_manager_install.manifest_hash.clone(),
        package_manager_executable_hash: package_manager_install.executable_hash.clone(),
    };
    build_env_plan(
        managed_runtime_roots,
        ManagedRuntimeKind::Python,
        runtime_install,
        package_manager_install,
        None,
        lockfile_path,
        hash_input,
    )
}

/// Validate one declared Node.js version against the supported asynchronous ESM baseline.
/// 根据受支持的异步 ESM 基线校验一个声明的 Node.js 版本。
///
/// `version` must be an exact semantic version from `node_runtime.version` or an interpreter probe.
/// `version` 必须是来自 `node_runtime.version` 或解释器探针的精确语义版本。
///
/// Returns unit for a supported runtime, otherwise a stable declaration or minimum-version error.
/// 受支持时返回空值，否则返回稳定的声明错误或最低版本错误。
pub(crate) fn validate_managed_node_runtime_version(version: &str) -> Result<(), String> {
    // DeclaredVersion is parsed before any filesystem lookup so unsupported runtimes fail without
    // creating environments or launching a worker that may crash inside its ESM loader.
    // DeclaredVersion 会在任何文件系统查找前解析，使不受支持的运行时在创建环境或启动可能于
    // ESM 加载器内部崩溃的 Worker 前失败。
    let declared_version = Version::parse(version.trim()).map_err(|error| {
        format!("node_runtime.version is not valid semantic version '{version}': {error}")
    })?;
    // MinimumVersion matches the first supported long-term Node runtime line for this protocol.
    // MinimumVersion 对应当前协议首个受支持的长期 Node 运行时版本线。
    let minimum_version = Version::new(22, 0, 0);
    if declared_version < minimum_version {
        return Err(format!(
            "managed Node runtime {version} is unsupported; minimum supported version is {MIN_MANAGED_NODE_RUNTIME_VERSION}"
        ));
    }
    Ok(())
}

/// Resolve one Node.js managed runtime environment plan from a trusted package declaration.
/// 根据可信包声明解析一个 Node.js 受管运行时环境计划。
///
/// `package` supplies canonical package/runtime roots and `spec` supplies the exact supported Node,
/// pnpm, manifest, and lockfile declaration.
/// `package` 提供规范包根与运行时根，`spec` 提供精确且受支持的 Node、pnpm、清单及锁文件声明。
///
/// Returns a reproducible environment plan, or a version, containment, manifest, or hashing error.
/// 返回可复现环境计划，或版本、包含关系、清单及哈希错误。
pub(crate) fn resolve_node_env_plan(
    package: &ManagedRuntimePackageContext,
    spec: &NodeRuntimeDependencySpec,
) -> Result<ManagedRuntimeEnvPlan, String> {
    validate_managed_node_runtime_version(&spec.version)?;
    validate_managed_runtime_resolver_version(&spec.package_manager_version)?;
    // ManagedRuntimeRoots is the single engine-selected authority for all three root roles.
    // ManagedRuntimeRoots 是三个根角色唯一的引擎选定授权。
    let managed_runtime_roots = package.managed_runtime_roots();
    managed_runtime_roots.validate_live_filesystem_identity()?;
    let platform = current_managed_runtime_platform_key()?;
    let runtime_dir = runtime_install_dir(
        managed_runtime_roots.distribution_root(),
        "node",
        &format!("node-{}-{}", spec.version, platform),
    );
    let runtime_install = resolve_managed_runtime_install_identity(
        managed_runtime_roots.distribution_root(),
        &runtime_dir,
        "node",
        &spec.version,
        &platform,
    )
    .map_err(|error| {
        format!(
            "managed runtime distribution source={}: {error}",
            managed_runtime_roots.distribution_source().as_str()
        )
    })?;
    let package_manager = spec.package_manager.as_managed_runtime_str().to_string();
    let package_manager_install_dir = runtime_install_dir(
        managed_runtime_roots.distribution_root(),
        "node",
        &format!("pnpm-{}", spec.package_manager_version),
    );
    let package_manager_install = resolve_managed_runtime_install_identity(
        managed_runtime_roots.distribution_root(),
        &package_manager_install_dir,
        "pnpm",
        &spec.package_manager_version,
        "any",
    )
    .map_err(|error| {
        format!(
            "managed runtime distribution source={}: {error}",
            managed_runtime_roots.distribution_source().as_str()
        )
    })?;
    // Optional canonical package manifest constrained to the trusted package root.
    // 限制在可信包根内的可选规范包清单。
    let package_manifest_path = if spec.package_json.trim().is_empty() {
        None
    } else {
        Some(package.resolve_existing_file(&spec.package_json, "node_runtime.package_json")?)
    };
    let package_manifest_hash = package_manifest_path
        .as_ref()
        .map(|path| sha256_file(path))
        .transpose()?;
    // Canonical lockfile constrained to the trusted package root.
    // 限制在可信包根内的规范锁文件。
    let lockfile_path = package.resolve_existing_file(&spec.lockfile, "node_runtime.lockfile")?;
    let lock_hash = sha256_file(&lockfile_path)?;
    let hash_input = ManagedRuntimeEnvHashInput {
        runtime: ManagedRuntimeKind::Node,
        runtime_version: spec.version.clone(),
        platform,
        package_manager,
        package_manager_version: spec.package_manager_version.clone(),
        lock_hash,
        package_manifest_hash,
        runtime_install_manifest_hash: runtime_install.manifest_hash.clone(),
        runtime_executable_hash: runtime_install.executable_hash.clone(),
        package_manager_install_manifest_hash: package_manager_install.manifest_hash.clone(),
        package_manager_executable_hash: package_manager_install.executable_hash.clone(),
    };
    build_env_plan(
        managed_runtime_roots,
        ManagedRuntimeKind::Node,
        runtime_install,
        package_manager_install,
        package_manifest_path,
        lockfile_path,
        hash_input,
    )
}

/// Read one managed runtime installation manifest from an installation directory.
/// 从安装目录读取一个受管运行时安装清单。
pub fn read_install_manifest(install_dir: &Path) -> Result<ManagedRuntimeInstallManifest, String> {
    read_install_manifest_with_hash(install_dir).map(|(manifest, _)| manifest)
}

/// Read and hash one installation manifest from the same exact byte snapshot.
/// 从同一份精确字节快照读取并哈希单个安装清单。
///
/// `install_dir` is the validated installation boundary containing `runtime-manifest.json`.
/// `install_dir` 是包含 `runtime-manifest.json` 的已校验安装边界。
///
/// Returns the parsed manifest with the SHA-256 of its original bytes, or an explicit file/read/
/// parse error; a UTF-8 BOM is accepted for parsing but remains part of the identity hash.
/// 返回已解析清单及其原始字节 SHA-256，或显式文件、读取及解析错误；解析接受 UTF-8 BOM，
/// 但 BOM 仍属于身份哈希的一部分。
fn read_install_manifest_with_hash(
    install_dir: &Path,
) -> Result<(ManagedRuntimeInstallManifest, String), String> {
    let manifest_path = install_dir.join("runtime-manifest.json");
    managed_runtime_install_manifest_path_is_file(&manifest_path)?;
    // ManifestBytes is hashed before parsing so identity and parsed authority share one read.
    // ManifestBytes 在解析前完成哈希，使身份与解析授权共享同一次读取。
    let manifest_bytes = fs::read(&manifest_path).map_err(|error| {
        format!(
            "Failed to read {}: {}",
            render_managed_runtime_path(&manifest_path),
            error
        )
    })?;
    let manifest_hash = sha256_hex(&manifest_bytes);
    // PowerShell 5.1 may write UTF-8 JSON files with a BOM when Set-Content is used.
    // PowerShell 5.1 使用 Set-Content 写 UTF-8 JSON 时可能带有 BOM。
    let parse_bytes = manifest_bytes
        .strip_prefix(&[0xEF, 0xBB, 0xBF])
        .unwrap_or(&manifest_bytes);
    let manifest = serde_json::from_slice(parse_bytes).map_err(|error| {
        format!(
            "Failed to parse {}: {}",
            render_managed_runtime_path(&manifest_path),
            error
        )
    })?;
    Ok((manifest, manifest_hash))
}

/// Inspect whether one managed-runtime install manifest path is a file without hiding filesystem probe errors.
/// 检查单个受管运行时安装清单路径是否为文件，同时不隐藏文件系统探测错误。
///
/// The manifest_path parameter is the concrete `runtime-manifest.json` path under one install directory.
/// manifest_path 参数是单个安装目录下的具体 `runtime-manifest.json` 路径。
///
/// Return unit for an existing manifest file, or an explicit missing/probe/type error.
/// 已存在清单文件时返回 unit；缺失、探测或类型异常时返回显式错误。
fn managed_runtime_install_manifest_path_is_file(manifest_path: &Path) -> Result<(), String> {
    match fs::symlink_metadata(manifest_path) {
        Ok(metadata) if metadata.file_type().is_symlink() => Err(format!(
            "managed runtime install manifest must not be a symbolic link: {}",
            render_managed_runtime_path(manifest_path)
        )),
        Ok(metadata) if metadata.is_file() => Ok(()),
        Ok(_) => Err(format!(
            "managed runtime install manifest is not a file: {}",
            render_managed_runtime_path(manifest_path)
        )),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Err(format!(
            "managed runtime install manifest not found: {}",
            render_managed_runtime_path(manifest_path)
        )),
        Err(error) => Err(format!(
            "Failed to inspect managed runtime install manifest {}: {}",
            render_managed_runtime_path(manifest_path),
            error
        )),
    }
}

/// Build one complete managed runtime environment plan from normalized inputs.
/// 基于规范化输入构造一个完整受管运行时环境计划。
fn build_env_plan(
    managed_runtime_roots: Arc<ManagedRuntimeRoots>,
    runtime: ManagedRuntimeKind,
    runtime_install: ManagedRuntimeInstallIdentity,
    package_manager_install: ManagedRuntimeInstallIdentity,
    package_manifest_path: Option<PathBuf>,
    lockfile_path: PathBuf,
    hash_input: ManagedRuntimeEnvHashInput,
) -> Result<ManagedRuntimeEnvPlan, String> {
    let env_hash = compute_managed_runtime_env_hash(&hash_input);
    let env_dir = managed_env_dir(
        managed_runtime_roots.environment_root(),
        runtime,
        &hash_input.runtime_version,
        &env_hash,
    );
    let expected_marker = ManagedRuntimeEnvMarker::expected(&hash_input, env_hash.clone());
    Ok(ManagedRuntimeEnvPlan {
        runtime,
        platform: hash_input.platform,
        runtime_root: managed_runtime_roots.runtime_root().to_path_buf(),
        distribution_root: managed_runtime_roots.distribution_root().to_path_buf(),
        environment_root: managed_runtime_roots.environment_root().to_path_buf(),
        distribution_source: managed_runtime_roots.distribution_source(),
        environment_source: managed_runtime_roots.environment_source(),
        runtime_install_root: runtime_install.install_root,
        runtime_version: hash_input.runtime_version,
        runtime_executable: runtime_install.executable,
        runtime_install_manifest_hash: hash_input.runtime_install_manifest_hash,
        runtime_executable_hash: hash_input.runtime_executable_hash,
        package_manager: hash_input.package_manager,
        package_manager_version: hash_input.package_manager_version,
        package_manager_executable: package_manager_install.executable,
        package_manager_install_root: package_manager_install.install_root,
        package_manager_install_manifest_hash: hash_input.package_manager_install_manifest_hash,
        package_manager_executable_hash: hash_input.package_manager_executable_hash,
        managed_runtime_roots,
        package_manifest_path,
        lockfile_path,
        lock_hash: hash_input.lock_hash,
        package_manifest_hash: hash_input.package_manifest_hash,
        env_hash,
        env_dir,
        expected_marker,
    })
}

/// Return one managed runtime installation directory directly under a distribution root.
/// 返回直接位于发行根下的单个受管运行时安装目录。
///
/// `distribution_root` already points at the directory containing fixed `python` and `node`
/// families; `family` and `name` are trusted fixed or validated path components.
/// `distribution_root` 已直接指向包含固定 `python` 与 `node` 资产族的目录；`family` 与 `name`
/// 是可信固定或已校验路径组件。
///
/// Returns the lexical installation path without performing filesystem access.
/// 返回词法安装路径且不执行文件系统访问。
fn runtime_install_dir(distribution_root: &Path, family: &str, name: &str) -> PathBuf {
    distribution_root.join(family).join(name)
}

/// Resolve one runtime or package-manager installation and bind its exact byte identity.
/// 解析单个运行时或包管理器安装并绑定其精确字节身份。
///
/// `distribution_root` is the canonical host authority, `install_dir` is the fixed expected child,
/// and all expected fields must match the untrusted manifest exactly.
/// `distribution_root` 是规范宿主授权，`install_dir` 是固定预期子目录，全部期望字段必须与
/// 不可信清单精确匹配。
///
/// Returns canonical contained paths plus manifest/executable hashes, or a containment, manifest,
/// file-type, or hashing error.
/// 返回规范包含路径及清单与可执行文件哈希，或包含关系、清单、文件类型及哈希错误。
fn resolve_managed_runtime_install_identity(
    distribution_root: &Path,
    install_dir: &Path,
    expected_runtime: &str,
    expected_version: &str,
    expected_platform: &str,
) -> Result<ManagedRuntimeInstallIdentity, String> {
    // LiveDistributionRoot detects same-name redirection before resolving any installation child.
    // LiveDistributionRoot 在解析任何安装子目录前检测同名重定向。
    let live_distribution_root = fs::canonicalize(distribution_root).map_err(|error| {
        format!(
            "Failed to canonicalize managed runtime distribution root {}: {}",
            render_managed_runtime_path(distribution_root),
            error
        )
    })?;
    if live_distribution_root != distribution_root {
        return Err(format!(
            "managed runtime distribution root changed canonical identity: expected {}, got {}",
            render_managed_runtime_path(distribution_root),
            render_managed_runtime_path(&live_distribution_root)
        ));
    }
    ensure_managed_runtime_directory(&live_distribution_root, "managed runtime distribution root")?;
    // CanonicalInstallRoot follows links so an installation cannot escape the configured root.
    // CanonicalInstallRoot 跟随链接，使安装目录无法逃逸配置发行根。
    let canonical_install_root = fs::canonicalize(install_dir).map_err(|error| {
        format!(
            "Failed to canonicalize managed runtime install directory {}: {}",
            render_managed_runtime_path(install_dir),
            error
        )
    })?;
    if canonical_install_root == live_distribution_root
        || !canonical_install_root.starts_with(&live_distribution_root)
    {
        return Err(format!(
            "managed runtime install directory {} escapes distribution root {}",
            render_managed_runtime_path(&canonical_install_root),
            render_managed_runtime_path(&live_distribution_root)
        ));
    }
    ensure_managed_runtime_directory(&canonical_install_root, "managed runtime install directory")?;
    // ManifestSnapshot supplies both parsed authority and hash from the same exact read.
    // ManifestSnapshot 从同一次精确读取提供解析授权与哈希。
    let (manifest, manifest_hash) = read_install_manifest_with_hash(&canonical_install_root)?;
    let executable = resolve_install_executable_from_manifest(
        &canonical_install_root,
        &manifest,
        expected_runtime,
        expected_version,
        expected_platform,
    )?;
    let executable_hash = sha256_file(&executable)?;
    Ok(ManagedRuntimeInstallIdentity {
        install_root: canonical_install_root,
        executable,
        manifest_hash,
        executable_hash,
    })
}

/// Resolve and validate one executable from an installation manifest.
/// 从安装清单中解析并校验一个可执行文件。
///
/// `install_dir` is the declared installation boundary; the expected identity fields must match
/// the parsed manifest exactly before its untrusted executable path is resolved.
/// `install_dir` 是声明的安装边界；在解析其不可信可执行文件路径前，期望身份字段必须与清单精确匹配。
///
/// Returns the canonical real ordinary file strictly inside the canonical installation directory.
/// 返回严格位于规范安装目录内的规范真实普通文件。
#[cfg(test)]
fn resolve_install_executable(
    install_dir: &Path,
    expected_runtime: &str,
    expected_version: &str,
    expected_platform: &str,
) -> Result<PathBuf, String> {
    // Parsed installation metadata whose identity and executable path remain untrusted.
    // 已解析的安装元数据，其身份与可执行文件路径仍不可信。
    let manifest = read_install_manifest(install_dir)?;
    resolve_install_executable_from_manifest(
        install_dir,
        &manifest,
        expected_runtime,
        expected_version,
        expected_platform,
    )
}

/// Resolve one executable from a manifest already parsed from the selected installation object.
/// 从已由所选安装对象解析的清单中解析单个可执行文件。
///
/// `install_dir` is the declared boundary, `manifest` is untrusted parsed data, and the three
/// expected identity fields are authoritative caller inputs.
/// `install_dir` 是声明边界，`manifest` 是不可信解析数据，三个期望身份字段是调用方权威输入。
///
/// Returns one canonical ordinary file strictly inside the canonical installation directory, or a
/// schema, identity, path-safety, containment, or file-type error.
/// 返回严格位于规范安装目录内的规范普通文件，或 schema、身份、路径安全、包含关系及文件类型错误。
fn resolve_install_executable_from_manifest(
    install_dir: &Path,
    manifest: &ManagedRuntimeInstallManifest,
    expected_runtime: &str,
    expected_version: &str,
    expected_platform: &str,
) -> Result<PathBuf, String> {
    if manifest.schema_version != 1 {
        return Err(format!(
            "managed runtime manifest {} uses unsupported schema_version {}",
            render_managed_runtime_path(install_dir),
            manifest.schema_version
        ));
    }
    if manifest.runtime != expected_runtime {
        return Err(format!(
            "managed runtime manifest {} has runtime '{}', expected '{}'",
            render_managed_runtime_path(install_dir),
            manifest.runtime,
            expected_runtime
        ));
    }
    if manifest.version != expected_version {
        return Err(format!(
            "managed runtime manifest {} has version '{}', expected '{}'",
            render_managed_runtime_path(install_dir),
            manifest.version,
            expected_version
        ));
    }
    if manifest.platform != expected_platform {
        return Err(format!(
            "managed runtime manifest {} has platform '{}', expected '{}'",
            render_managed_runtime_path(install_dir),
            manifest.platform,
            expected_platform
        ));
    }
    // Manifest paths are data, not authority: only nonempty normal relative components are valid.
    // 清单路径只是数据而非授权：仅允许非空的普通相对路径组件。
    let relative_executable = Path::new(&manifest.executable);
    if !managed_install_executable_relative_path_is_safe(relative_executable) {
        return Err(format!(
            "managed runtime manifest {} has unsafe relative executable path '{}'",
            render_managed_runtime_path(install_dir),
            manifest.executable
        ));
    }
    // Canonical installation root is the authority boundary used after following every link.
    // 规范安装根是在跟随全部链接后使用的授权边界。
    let canonical_install_dir = fs::canonicalize(install_dir).map_err(|error| {
        format!(
            "Failed to canonicalize managed runtime install directory {}: {}",
            render_managed_runtime_path(install_dir),
            error
        )
    })?;
    if !canonical_install_dir.is_dir() {
        return Err(format!(
            "managed runtime install path is not a directory: {}",
            render_managed_runtime_path(&canonical_install_dir)
        ));
    }
    // Canonical executable resolution rejects missing targets and exposes symlink escapes.
    // 规范可执行文件解析会拒绝缺失目标并暴露符号链接逃逸。
    let executable_candidate = canonical_install_dir.join(relative_executable);
    let canonical_executable = fs::canonicalize(&executable_candidate).map_err(|error| {
        format!(
            "Failed to canonicalize managed runtime executable {}: {}",
            render_managed_runtime_path(&executable_candidate),
            error
        )
    })?;
    if canonical_executable == canonical_install_dir
        || !canonical_executable.starts_with(&canonical_install_dir)
    {
        return Err(format!(
            "managed runtime executable {} escapes install directory {}",
            render_managed_runtime_path(&canonical_executable),
            render_managed_runtime_path(&canonical_install_dir)
        ));
    }
    // Followed-target metadata used to require one real ordinary file rather than a directory.
    // 跟随目标后的元数据，用于要求真实普通文件而非目录。
    let executable_metadata = fs::metadata(&canonical_executable).map_err(|error| {
        format!(
            "Failed to inspect managed runtime executable {}: {}",
            render_managed_runtime_path(&canonical_executable),
            error
        )
    })?;
    if !executable_metadata.is_file() {
        return Err(format!(
            "managed runtime executable is not a file: {}",
            render_managed_runtime_path(&canonical_executable)
        ));
    }
    Ok(canonical_executable)
}

/// Return whether one manifest executable is a nonempty platform-safe relative path.
/// 返回单个清单可执行文件是否为非空且平台安全的相对路径。
///
/// `path` is untrusted manifest data and therefore may contain roots, parent traversal, prefixes,
/// or Windows alternate-data-stream syntax.
/// `path` 是不可信清单数据，因此可能包含根、父目录穿越、前缀或 Windows 备用数据流语法。
///
/// Returns true only when every component is an ordinary safe filename component.
/// 仅当每个组件都是普通安全文件名组件时返回 true。
fn managed_install_executable_relative_path_is_safe(path: &Path) -> bool {
    !path.as_os_str().is_empty()
        && path.components().all(|component| match component {
            Component::Normal(value) => managed_install_executable_component_is_safe(value),
            _ => false,
        })
}

/// Return whether one normal manifest path component is safe on Windows.
/// 返回单个普通清单路径组件在 Windows 上是否安全。
///
/// `component` is one normal relative component; a colon would select an NTFS alternate data
/// stream rather than the real ordinary file required by the install contract.
/// `component` 是一个普通相对组件；冒号会选择 NTFS 备用数据流，而非安装契约要求的真实普通文件。
///
/// Returns false for alternate-data-stream syntax and true for other normal components.
/// 对备用数据流语法返回 false，对其他普通组件返回 true。
#[cfg(windows)]
fn managed_install_executable_component_is_safe(component: &std::ffi::OsStr) -> bool {
    use std::os::windows::ffi::OsStrExt;

    !component.encode_wide().any(|unit| unit == u16::from(b':'))
}

/// Return whether one normal manifest path component is safe on non-Windows platforms.
/// 返回单个普通清单路径组件在非 Windows 平台上是否安全。
///
/// `component` has already been classified as an ordinary relative component.
/// `component` 已被分类为普通相对组件。
///
/// Returns true because non-Windows component parsing has no NTFS alternate-stream syntax.
/// 返回 true，因为非 Windows 组件解析不存在 NTFS 备用数据流语法。
#[cfg(not(windows))]
fn managed_install_executable_component_is_safe(_component: &std::ffi::OsStr) -> bool {
    true
}

/// Feed one labeled string field into a stable SHA-256 hasher.
/// 将一个带标签的字符串字段写入稳定 SHA-256 hasher。
fn hash_field(hasher: &mut Sha256, label: &str, value: impl AsRef<str>) {
    hasher.update(label.as_bytes());
    hasher.update([0]);
    hasher.update(value.as_ref().as_bytes());
    hasher.update([0xff]);
}

/// Return the directory prefix used for runtime-version environment groups.
/// 返回运行时版本环境分组使用的目录前缀。
fn runtime_prefix(runtime: ManagedRuntimeKind) -> &'static str {
    match runtime {
        ManagedRuntimeKind::Python => "py",
        ManagedRuntimeKind::Node => "node",
    }
}

#[cfg(test)]
mod tests {
    #[cfg(windows)]
    use super::managed_install_executable_relative_path_is_safe;
    use super::{
        ManagedRuntimeBackupRecoveryAction, ManagedRuntimeBackupRecoveryRecord,
        ManagedRuntimeEnvHashInput, ManagedRuntimeEnvMarker, ManagedRuntimeEnvPlan,
        ManagedRuntimeKind, ManagedRuntimeRootSource, ManagedRuntimeRoots,
        acquire_managed_runtime_env_file_lock, acquire_ready_managed_env_lease,
        capture_managed_directory_identity, compute_managed_runtime_env_hash,
        configure_managed_command_base_environment, copy_dir_recursive,
        current_managed_runtime_platform_key, finish_build_dir,
        finish_build_dir_with_backup_remover, managed_env_dir, managed_env_is_ready,
        managed_env_marker_matches, managed_env_marker_path, prepare_build_dir_with_sequence,
        read_install_manifest, reserve_managed_runtime_backup_recovery_slot,
        resolve_install_executable, resolve_managed_runtime_install,
        resolve_managed_runtime_install_identity, resolve_node_env_plan, resolve_python_env_plan,
        sha256_file, sha256_hex, validate_managed_runtime_plan_assets,
        verify_managed_runtime_build_input_hash, write_expected_marker,
    };
    use crate::runtime::managed_package::ManagedRuntimePackageContext;
    use crate::runtime::path::render_host_visible_path;
    use crate::skill::dependencies::{
        NodeRuntimeDependencySpec, NodeRuntimePackageManager, PythonRuntimeDependencySpec,
        PythonRuntimePackageManager,
    };
    use std::fs;
    #[cfg(unix)]
    use std::os::unix::fs::symlink as create_unix_symlink;
    #[cfg(windows)]
    use std::os::windows::fs::{
        symlink_dir as create_windows_directory_symlink,
        symlink_file as create_windows_file_symlink,
    };
    use std::path::{Path, PathBuf};
    use std::process::{Command, Stdio};
    use std::sync::{Arc, Mutex};
    use std::thread;
    use std::time::Duration;

    /// Create one test file symlink that points at the requested target path.
    /// 创建一个指向指定目标路径的测试文件符号链接。
    #[cfg(unix)]
    fn create_test_file_symlink(link_path: &Path, target_path: &Path) -> bool {
        create_unix_symlink(target_path, link_path).expect("create test file symlink");
        true
    }

    /// Create one test directory symlink that points at the requested target path.
    /// 创建一个指向指定目标路径的测试目录符号链接。
    #[cfg(unix)]
    fn create_test_directory_symlink(link_path: &Path, target_path: &Path) -> bool {
        create_unix_symlink(target_path, link_path).expect("create test directory symlink");
        true
    }

    /// Build one trusted Skill package context backed by real temporary directories.
    /// 基于真实临时目录构造一个可信 Skill 包上下文。
    ///
    /// `package_root` identifies the package directory used to resolve dependency files.
    /// `package_root` 标识用于解析依赖文件的包目录。
    ///
    /// `runtime_root` identifies the runtime directory that owns managed installations and environments.
    /// `runtime_root` 标识拥有受管安装与环境的运行时目录。
    ///
    /// Return the validated package context required by managed runtime plan resolvers.
    /// 返回受管运行时计划解析器所需的已验证包上下文。
    fn make_test_package_context(
        package_root: &Path,
        runtime_root: &Path,
    ) -> Arc<ManagedRuntimePackageContext> {
        fs::create_dir_all(package_root).expect("create managed runtime test package root");
        fs::create_dir_all(runtime_root).expect("create managed runtime test runtime root");
        ManagedRuntimePackageContext::for_skill(
            "managed-runtime-test",
            package_root,
            runtime_root,
            None,
        )
        .expect("build managed runtime test package context")
    }

    /// Return whether one Windows symlink-dependent test should be skipped because the host lacks symlink privileges.
    /// 返回当前 Windows 符号链接相关测试是否应因宿主缺少符号链接权限而跳过。
    #[cfg(windows)]
    fn should_skip_windows_symlink_test(error: &std::io::Error) -> bool {
        /// Windows privilege error returned when symlink creation requires elevation or Developer Mode.
        /// 当符号链接创建需要管理员权限或开发者模式时 Windows 返回的权限错误码。
        const ERROR_PRIVILEGE_NOT_HELD: i32 = 1314;

        error.kind() == std::io::ErrorKind::PermissionDenied
            || error.raw_os_error() == Some(ERROR_PRIVILEGE_NOT_HELD)
    }

    /// Create one test file symlink that points at the requested target path.
    /// 创建一个指向指定目标路径的测试文件符号链接。
    #[cfg(windows)]
    fn create_test_file_symlink(link_path: &Path, target_path: &Path) -> bool {
        match create_windows_file_symlink(target_path, link_path) {
            Ok(()) => true,
            Err(error) if should_skip_windows_symlink_test(&error) => {
                eprintln!(
                    "skip symlink-dependent test because Windows symlink privileges are unavailable: {error}"
                );
                false
            }
            Err(error) => panic!("create test file symlink: {error}"),
        }
    }

    /// Create one test directory symlink that points at the requested target path.
    /// 创建一个指向指定目标路径的测试目录符号链接。
    #[cfg(windows)]
    fn create_test_directory_symlink(link_path: &Path, target_path: &Path) -> bool {
        match create_windows_directory_symlink(target_path, link_path) {
            Ok(()) => true,
            Err(error) if should_skip_windows_symlink_test(&error) => {
                eprintln!(
                    "skip directory-symlink test because Windows symlink privileges are unavailable: {error}"
                );
                false
            }
            Err(error) => panic!("create test directory symlink: {error}"),
        }
    }

    /// Verify that environment hashes are stable and include lockfile content changes.
    /// 验证环境哈希保持稳定，并且会纳入锁文件内容变化。
    #[test]
    fn env_hash_is_stable_and_lock_sensitive() {
        let input = ManagedRuntimeEnvHashInput {
            runtime: ManagedRuntimeKind::Python,
            runtime_version: "3.12.8".to_string(),
            platform: "windows-x64".to_string(),
            package_manager: "uv".to_string(),
            package_manager_version: "0.11.28".to_string(),
            lock_hash: sha256_hex(b"requests==2.32.3"),
            package_manifest_hash: None,
            runtime_install_manifest_hash: "python-manifest".to_string(),
            runtime_executable_hash: "python-executable".to_string(),
            package_manager_install_manifest_hash: "uv-manifest".to_string(),
            package_manager_executable_hash: "uv-executable".to_string(),
        };
        let same_hash = compute_managed_runtime_env_hash(&input);
        let repeated_hash = compute_managed_runtime_env_hash(&input);
        let changed_hash = compute_managed_runtime_env_hash(&ManagedRuntimeEnvHashInput {
            lock_hash: sha256_hex(b"requests==2.32.4"),
            ..input.clone()
        });
        let changed_runtime_hash = compute_managed_runtime_env_hash(&ManagedRuntimeEnvHashInput {
            runtime_executable_hash: "different-python-executable".to_string(),
            ..input
        });

        assert_eq!(same_hash, repeated_hash);
        assert_ne!(same_hash, changed_hash);
        assert_ne!(same_hash, changed_runtime_hash);
    }

    /// Verify that a copied build input cannot diverge from its plan-time environment identity.
    /// 验证已复制构建输入不能偏离其计划阶段环境身份。
    #[test]
    fn managed_runtime_build_input_requires_exact_planned_hash() {
        // PrivateCopy models the only file path later supplied to uv or pnpm.
        // PrivateCopy 模拟之后传给 uv 或 pnpm 的唯一文件路径。
        let root = make_test_root("verified-build-input");
        fs::create_dir_all(&root).expect("create verified build input root");
        let private_copy = root.join("dependency.lock");
        fs::write(&private_copy, b"version=one").expect("write planned build input");
        let expected_hash = sha256_hex(b"version=one");

        verify_managed_runtime_build_input_hash(
            &private_copy,
            &expected_hash,
            "test dependency input",
        )
        .expect("accept exact planned build input");
        fs::write(&private_copy, b"version=two").expect("replace copied build input bytes");
        let error = verify_managed_runtime_build_input_hash(
            &private_copy,
            &expected_hash,
            "test dependency input",
        )
        .expect_err("reject build input changed after planning");
        assert!(error.contains("changed after environment planning"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify that expected markers match only exact environment identities.
    /// 验证期望标记只匹配完全一致的环境身份。
    #[test]
    fn marker_match_requires_exact_identity() {
        let input = ManagedRuntimeEnvHashInput {
            runtime: ManagedRuntimeKind::Node,
            runtime_version: "24.18.0".to_string(),
            platform: "linux-x64".to_string(),
            package_manager: "pnpm".to_string(),
            package_manager_version: "11.11.0".to_string(),
            lock_hash: "lock".to_string(),
            package_manifest_hash: Some("package".to_string()),
            runtime_install_manifest_hash: "node-manifest".to_string(),
            runtime_executable_hash: "node-executable".to_string(),
            package_manager_install_manifest_hash: "pnpm-manifest".to_string(),
            package_manager_executable_hash: "pnpm-executable".to_string(),
        };
        let env_hash = compute_managed_runtime_env_hash(&input);
        let expected = ManagedRuntimeEnvMarker::expected(&input, env_hash);
        let mut actual = expected.clone();

        assert!(managed_env_marker_matches(&actual, &expected));
        actual.lock_hash = "other".to_string();
        assert!(!managed_env_marker_matches(&actual, &expected));
    }

    /// Verify that managed environment directories use runtime and version group names.
    /// 验证受管环境目录会使用运行时与版本分组名称。
    #[test]
    fn managed_env_dir_uses_runtime_version_group() {
        let path = managed_env_dir(
            Path::new("runtime-root"),
            ManagedRuntimeKind::Python,
            "3.12.8",
            "abc",
        );
        assert!(path.ends_with(Path::new("python/py-3.12.8/abc")));
    }

    /// Verify that marker readiness checks return true only after writing the expected marker.
    /// 验证 marker 就绪检查只有在写入期望标记后才返回 true。
    #[test]
    fn managed_env_ready_checks_expected_marker() {
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        let root = make_test_root("ready-marker");
        let runtime_root = root.join("runtime");
        let package_root = root.join("skill");
        fs::create_dir_all(package_root.join("python")).unwrap();
        fs::write(
            package_root.join("python/requirements.lock"),
            b"requests==2.32.3",
        )
        .unwrap();
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("cpython-3.14.4-{}", platform)),
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );
        let package = make_test_package_context(&package_root, &runtime_root);
        let plan = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "python/requirements.lock".to_string(),
                required: true,
            },
        )
        .expect("python env plan should resolve");

        assert!(!managed_env_is_ready(&plan).expect("ready check should work"));
        fs::create_dir_all(&plan.env_dir).unwrap();
        write_expected_marker(&plan.env_dir, &plan.expected_marker).unwrap();
        assert!(managed_env_is_ready(&plan).expect("ready check should work"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify a matching marker cannot make a symbolic-link environment directory trusted.
    /// 验证匹配 marker 不能使符号链接环境目录获得信任。
    #[test]
    fn managed_env_ready_rejects_symbolic_link_environment_directory() {
        // Plan points at one absent stable name while Outside contains a forged matching marker.
        // Plan 指向一个不存在的稳定名称，Outside 包含伪造的匹配 marker。
        let root = make_test_root("symlink-environment-directory");
        let plan = make_environment_file_lock_test_plan(&root);
        let outside = root.join("outside-environment");
        fs::create_dir_all(plan.env_dir.parent().expect("managed env parent"))
            .expect("create managed env parent");
        fs::create_dir(&outside).expect("create outside environment");
        write_expected_marker(&outside, &plan.expected_marker)
            .expect("write forged outside environment marker");
        if !create_test_directory_symlink(&plan.env_dir, &outside) {
            let _ = fs::remove_dir_all(root);
            return;
        }

        let error = managed_env_is_ready(&plan)
            .expect_err("symbolic-link environment directory must be rejected");
        assert!(error.contains("must not be a symbolic link"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify a real environment cannot accept a symbolic-link readiness marker.
    /// 验证真实环境不能接受符号链接形式的就绪 marker。
    #[test]
    fn managed_env_ready_rejects_symbolic_link_marker() {
        // OutsideMarker carries valid bytes but its foreign name cannot become trusted by linking.
        // OutsideMarker 携带有效字节，但其外部名称不能通过链接获得信任。
        let root = make_test_root("symlink-environment-marker");
        let plan = make_environment_file_lock_test_plan(&root);
        fs::create_dir_all(&plan.env_dir).expect("create real managed environment");
        let outside = root.join("outside-marker-root");
        fs::create_dir(&outside).expect("create outside marker root");
        write_expected_marker(&outside, &plan.expected_marker)
            .expect("write forged outside marker");
        let outside_marker = managed_env_marker_path(&outside);
        let marker_link = managed_env_marker_path(&plan.env_dir);
        if !create_test_file_symlink(&marker_link, &outside_marker) {
            let _ = fs::remove_dir_all(root);
            return;
        }

        let error = managed_env_is_ready(&plan)
            .expect_err("symbolic-link environment marker must be rejected");
        assert!(error.contains("must not be a symbolic link"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify marker readiness checks reject marker paths that exist as directories.
    /// 验证 marker 就绪检查会拒绝以目录形式存在的 marker 路径。
    #[test]
    fn managed_env_ready_rejects_directory_marker() {
        // Platform key used to create matching runtime install manifests.
        // 用于创建匹配运行时安装清单的平台键。
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        // Temporary root that isolates the directory marker fixture.
        // 隔离目录型 marker 夹具的临时根目录。
        let root = make_test_root("directory-marker");
        // Runtime root containing the fake installed runtime manifests.
        // 包含伪造已安装运行时清单的运行时根目录。
        let runtime_root = root.join("runtime");
        // Skill directory containing the Python lockfile fixture.
        // 包含 Python lockfile 夹具的 skill 目录。
        let package_root = root.join("skill");
        fs::create_dir_all(package_root.join("python")).unwrap();
        fs::write(
            package_root.join("python/requirements.lock"),
            b"requests==2.32.3",
        )
        .unwrap();
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("cpython-3.14.4-{}", platform)),
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );
        // Environment plan whose marker path will be occupied by a directory.
        // 其 marker 路径将被目录占用的环境计划。
        let package = make_test_package_context(&package_root, &runtime_root);
        let plan = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "python/requirements.lock".to_string(),
                required: true,
            },
        )
        .expect("python env plan should resolve");
        // Directory occupying the exact marker file path.
        // 占据精确 marker 文件路径的目录。
        let marker_path = managed_env_marker_path(&plan.env_dir);
        fs::create_dir_all(&marker_path).expect("directory marker should be created");

        // Error returned before the directory marker can behave like a missing marker.
        // 在目录型 marker 表现得像缺失 marker 之前返回的错误。
        let error =
            managed_env_is_ready(&plan).expect_err("directory marker readiness check should fail");

        assert!(
            error.contains("Managed runtime env marker is not a file"),
            "unexpected error: {}",
            error
        );
        assert!(
            error.contains(&render_host_visible_path(&marker_path)),
            "unexpected error: {}",
            error
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify install manifest readers reject directory manifests before JSON reading.
    /// 验证安装清单读取器会在 JSON 读取前拒绝目录型清单。
    #[test]
    fn read_install_manifest_rejects_directory_manifest() {
        // Temporary root that isolates the directory install-manifest fixture.
        // 隔离目录型安装清单夹具的临时根目录。
        let root = make_test_root("directory-install-manifest");
        // Install directory whose runtime-manifest path will be occupied by a directory.
        // 其 runtime-manifest 路径将被目录占用的安装目录。
        let install_dir = root.join("runtime-install");
        // Directory occupying the exact runtime-manifest.json path.
        // 占据精确 runtime-manifest.json 路径的目录。
        let manifest_path = install_dir.join("runtime-manifest.json");
        fs::create_dir_all(&manifest_path).expect("directory install manifest should be created");

        // Error returned before the directory manifest can be passed to read_to_string.
        // 在目录型清单被传递给 read_to_string 之前返回的错误。
        let error =
            read_install_manifest(&install_dir).expect_err("directory manifest should fail");

        assert!(
            error.contains("managed runtime install manifest is not a file"),
            "unexpected error: {}",
            error
        );
        assert!(
            error.contains(&render_host_visible_path(&manifest_path)),
            "unexpected error: {}",
            error
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify install manifests reject absolute and parent-traversing executable paths.
    /// 验证安装清单会拒绝绝对及父目录穿越形式的可执行文件路径。
    #[test]
    fn install_manifest_rejects_unsafe_relative_executable_paths() {
        // Temporary root containing one isolated synthetic installation.
        // 包含单个隔离合成安装的临时根目录。
        let root = make_test_root("unsafe-install-executable-path");
        // Installation directory whose manifest is rewritten for each unsafe path.
        // 针对每个不安全路径重写清单的安装目录。
        let install_dir = root.join("runtime-install");
        fs::create_dir_all(&install_dir).expect("create unsafe manifest install directory");
        // Existing outside file used to form a concrete absolute-path attack.
        // 用于构造具体绝对路径攻击的既有外部文件。
        let outside_executable = root.join("outside-tool");
        fs::write(&outside_executable, b"outside").expect("write outside executable fixture");
        // Unsafe paths that must be rejected before filesystem target authorization.
        // 必须在文件系统目标授权前被拒绝的不安全路径。
        let unsafe_paths = [
            outside_executable.to_string_lossy().into_owned(),
            "../outside-tool".to_string(),
            "bin/../outside-tool".to_string(),
            "./tool".to_string(),
        ];
        for unsafe_path in unsafe_paths {
            // Strict manifest payload carrying the current unsafe executable value.
            // 携带当前不安全可执行文件值的严格清单载荷。
            let payload = serde_json::json!({
                "schema_version": 1,
                "runtime": "tool",
                "version": "1.0.0",
                "platform": "test",
                "executable": unsafe_path,
            });
            fs::write(
                install_dir.join("runtime-manifest.json"),
                serde_json::to_vec_pretty(&payload).expect("encode unsafe install manifest"),
            )
            .expect("write unsafe install manifest");

            // Explicit validation error proving the untrusted path never becomes authority.
            // 证明不可信路径绝不会成为授权依据的显式校验错误。
            let error = resolve_install_executable(&install_dir, "tool", "1.0.0", "test")
                .expect_err("unsafe install executable path should fail");

            assert!(
                error.contains("unsafe relative executable path"),
                "unexpected error for {unsafe_path:?}: {error}"
            );
        }
        let _ = fs::remove_dir_all(root);
    }

    /// Verify Windows alternate-data-stream syntax is not accepted as a real executable file.
    /// 验证 Windows 备用数据流语法不会被接受为真实可执行文件。
    #[cfg(windows)]
    #[test]
    fn install_manifest_rejects_windows_alternate_data_stream_path() {
        assert!(!managed_install_executable_relative_path_is_safe(
            Path::new("bin/tool.exe:payload")
        ));
    }

    /// Verify a manifest executable symlink cannot escape its canonical installation root.
    /// 验证清单可执行文件符号链接无法逃逸其规范安装根。
    #[test]
    fn install_manifest_rejects_executable_symlink_escape() {
        // Temporary root separating the installation boundary from the outside target.
        // 将安装边界与外部目标隔离的临时根目录。
        let root = make_test_root("install-executable-symlink-escape");
        // Installation directory that owns the untrusted symlink entry.
        // 拥有不可信符号链接条目的安装目录。
        let install_dir = root.join("runtime-install");
        fs::create_dir_all(install_dir.join("bin")).expect("create symlink install bin directory");
        // Real ordinary file intentionally located outside the installation boundary.
        // 有意位于安装边界之外的真实普通文件。
        let outside_executable = root.join("outside-tool");
        fs::write(&outside_executable, b"outside").expect("write symlink target fixture");
        // Manifest-relative link whose canonical target leaves the install directory.
        // 规范目标离开安装目录的清单相对链接。
        let executable_link = install_dir.join("bin/tool");
        if !create_test_file_symlink(&executable_link, &outside_executable) {
            let _ = fs::remove_dir_all(root);
            return;
        }
        // Validly shaped manifest isolates the canonical containment check from syntax checks.
        // 形态合法的清单可将规范包含校验与语法校验隔离。
        let payload = serde_json::json!({
            "schema_version": 1,
            "runtime": "tool",
            "version": "1.0.0",
            "platform": "test",
            "executable": "bin/tool",
        });
        fs::write(
            install_dir.join("runtime-manifest.json"),
            serde_json::to_vec_pretty(&payload).expect("encode symlink escape manifest"),
        )
        .expect("write symlink escape manifest");

        // Error emitted only after the symlink target has been canonicalized.
        // 仅在符号链接目标完成规范化后产生的错误。
        let error = resolve_install_executable(&install_dir, "tool", "1.0.0", "test")
            .expect_err("symlink escape should fail");

        assert!(
            error.contains("escapes install directory"),
            "unexpected error: {error}"
        );
        assert!(
            error.contains(&render_host_visible_path(
                &fs::canonicalize(&outside_executable).expect("canonical outside executable")
            )),
            "unexpected error: {error}"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify the managed command baseline removes secrets and preserves only controlled PATH entries.
    /// 验证受管命令基线会移除密钥，并仅保留受控 PATH 条目。
    #[test]
    fn managed_command_environment_hides_host_secrets_and_keeps_controlled_path() {
        // Temporary controlled home and executable-search directories.
        // 临时受控 home 与可执行文件搜索目录。
        let root = make_test_root("managed-command-environment");
        // Isolated home/temp root supplied to the child.
        // 提供给子进程的隔离 home/temp 根。
        let controlled_home = root.join("home");
        // Two exact PATH entries proving order and exclusivity.
        // 用于证明顺序与排他性的两个精确 PATH 条目。
        let first_bin = root.join("runtime-bin");
        let second_bin = root.join("package-manager-bin");
        fs::create_dir_all(&controlled_home).expect("create controlled command home");
        fs::create_dir_all(&first_bin).expect("create first controlled bin");
        fs::create_dir_all(&second_bin).expect("create second controlled bin");
        // Current test executable is a real ordinary binary that must still launch after env_clear.
        // 当前测试可执行文件是真实普通二进制文件，在 env_clear 后仍必须能够启动。
        let current_executable = std::env::current_exe().expect("resolve current test executable");
        // Child test-harness invocation seeded with a representative host credential.
        // 预置代表性宿主凭据的子测试框架调用。
        let mut command = Command::new(&current_executable);
        command
            .arg("--list")
            .env("AWS_SECRET_ACCESS_KEY", "must-not-cross-managed-boundary");
        configure_managed_command_base_environment(
            &mut command,
            &controlled_home,
            &[first_bin.clone(), second_bin.clone()],
        )
        .expect("configure isolated managed command environment");
        // Explicit environment entries retained after env_clear and controlled reconstruction.
        // env_clear 与受控重建后保留的显式环境条目。
        let command_environment = command
            .get_envs()
            .map(|(key, value)| {
                (
                    key.to_string_lossy().into_owned(),
                    value.map(|value| value.to_os_string()),
                )
            })
            .collect::<std::collections::HashMap<_, _>>();
        assert!(!command_environment.contains_key("AWS_SECRET_ACCESS_KEY"));
        // Platform-native PATH value reconstructed from only the two authorized directories.
        // 仅根据两个已授权目录重建的平台原生 PATH 值。
        let expected_path =
            std::env::join_paths([&first_bin, &second_bin]).expect("join expected controlled PATH");
        assert_eq!(
            command_environment
                .get("PATH")
                .and_then(Option::as_ref)
                .expect("controlled PATH environment"),
            &expected_path
        );
        assert_eq!(
            command_environment
                .get("HOME")
                .and_then(Option::as_ref)
                .expect("controlled HOME environment"),
            controlled_home.as_os_str()
        );
        // Exit status proving a real executable remains launchable with the minimal environment.
        // 用于证明真实可执行文件在最小环境中仍可启动的退出状态。
        let status = command
            .status()
            .expect("launch with managed command environment");
        assert!(
            status.success(),
            "minimal managed environment should launch"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Build one synthetic environment plan shared by the parent and child lock probes.
    /// 构造一份由父子锁探针共享的合成环境计划。
    ///
    /// `root` is the cross-process fixture root and the return value uses one stable env hash.
    /// `root` 是跨进程夹具根，返回值使用一个稳定环境哈希。
    fn make_environment_file_lock_test_plan(root: &Path) -> ManagedRuntimeEnvPlan {
        // DistributionRoot contains real synthetic assets so lifecycle acquisition exercises the
        // same identity validation as production plans in both parent and child processes.
        // DistributionRoot 包含真实合成资产，使父子进程中的生命周期获取执行与生产计划相同的
        // 身份校验。
        let distribution_root = root.join("runtimes");
        let environment_root = root.join("managed-envs");
        fs::create_dir_all(&environment_root).expect("create lock test environment root");
        let runtime_install_root = distribution_root
            .join("python")
            .join("cpython-3.14.4-test-platform");
        let package_manager_install_root = distribution_root
            .join("python")
            .join("uv-0.11.28-test-platform");
        write_install_manifest(
            &runtime_install_root,
            "python",
            "3.14.4",
            "test-platform",
            platform_executable("python"),
        );
        write_install_manifest(
            &package_manager_install_root,
            "uv",
            "0.11.28",
            "test-platform",
            platform_executable("uv"),
        );
        let managed_runtime_roots = Arc::new(
            ManagedRuntimeRoots::new(root, Some(&distribution_root), Some(&environment_root))
                .expect("create lock test managed runtime roots"),
        );
        // RuntimeInstall and PackageManagerInstall capture the exact bytes used by plan validation.
        // RuntimeInstall 与 PackageManagerInstall 捕获计划校验使用的精确字节。
        let runtime_install = resolve_managed_runtime_install_identity(
            managed_runtime_roots.distribution_root(),
            &runtime_install_root,
            "python",
            "3.14.4",
            "test-platform",
        )
        .expect("resolve lock test Python install");
        let package_manager_install = resolve_managed_runtime_install_identity(
            managed_runtime_roots.distribution_root(),
            &package_manager_install_root,
            "uv",
            "0.11.28",
            "test-platform",
        )
        .expect("resolve lock test uv install");
        let hash_input = ManagedRuntimeEnvHashInput {
            runtime: ManagedRuntimeKind::Python,
            runtime_version: "3.14.4".to_string(),
            platform: "test-platform".to_string(),
            package_manager: "uv".to_string(),
            package_manager_version: "0.11.28".to_string(),
            lock_hash: "lock".to_string(),
            package_manifest_hash: None,
            runtime_install_manifest_hash: runtime_install.manifest_hash.clone(),
            runtime_executable_hash: runtime_install.executable_hash.clone(),
            package_manager_install_manifest_hash: package_manager_install.manifest_hash.clone(),
            package_manager_executable_hash: package_manager_install.executable_hash.clone(),
        };
        let env_hash = "cross-process-lock-hash".to_string();
        ManagedRuntimeEnvPlan {
            runtime: ManagedRuntimeKind::Python,
            platform: hash_input.platform.clone(),
            runtime_root: managed_runtime_roots.runtime_root().to_path_buf(),
            distribution_root: managed_runtime_roots.distribution_root().to_path_buf(),
            environment_root: managed_runtime_roots.environment_root().to_path_buf(),
            distribution_source: ManagedRuntimeRootSource::HostConfigured,
            environment_source: ManagedRuntimeRootSource::HostConfigured,
            runtime_install_root: runtime_install.install_root,
            runtime_version: hash_input.runtime_version.clone(),
            runtime_executable: runtime_install.executable,
            runtime_install_manifest_hash: hash_input.runtime_install_manifest_hash.clone(),
            runtime_executable_hash: hash_input.runtime_executable_hash.clone(),
            package_manager: hash_input.package_manager.clone(),
            package_manager_version: hash_input.package_manager_version.clone(),
            package_manager_executable: package_manager_install.executable,
            package_manager_install_root: package_manager_install.install_root,
            package_manager_install_manifest_hash: hash_input
                .package_manager_install_manifest_hash
                .clone(),
            package_manager_executable_hash: hash_input.package_manager_executable_hash.clone(),
            managed_runtime_roots: Arc::clone(&managed_runtime_roots),
            package_manifest_path: None,
            lockfile_path: root.join("requirements.lock"),
            lock_hash: hash_input.lock_hash.clone(),
            package_manifest_hash: None,
            env_hash: env_hash.clone(),
            env_dir: managed_env_dir(
                managed_runtime_roots.environment_root(),
                ManagedRuntimeKind::Python,
                &hash_input.runtime_version,
                &env_hash,
            ),
            expected_marker: ManagedRuntimeEnvMarker::expected(&hash_input, env_hash),
        }
    }

    /// Child-process probe that blocks on the exact OS file lock selected by its parent test.
    /// 子进程探针，会在父测试选定的精确操作系统文件锁上阻塞。
    #[test]
    fn managed_runtime_environment_file_lock_child_probe() {
        let Some(root) = std::env::var_os("LUASKILLS_TEST_ENV_LOCK_ROOT") else {
            return;
        };
        let root = PathBuf::from(root);
        let started_path = root.join("child-started");
        let acquired_path = root.join("child-acquired");
        fs::write(&started_path, b"started").expect("write child lock start signal");
        let plan = make_environment_file_lock_test_plan(&root);
        let guard = acquire_managed_runtime_env_file_lock(&plan)
            .expect("child acquires managed environment file lock");
        fs::write(&acquired_path, b"acquired").expect("write child lock acquisition signal");
        drop(guard);
    }

    /// Verify separate processes serialize construction for one exact environment identity.
    /// 验证独立进程会为同一个精确环境身份串行化构建过程。
    #[test]
    fn managed_runtime_environment_file_lock_serializes_processes() {
        let root = make_test_root("cross-process-env-lock");
        fs::create_dir_all(&root).expect("create file-lock test root");
        let plan = make_environment_file_lock_test_plan(&root);
        // FirstGuard owns the OS lock while another process opens and locks a distinct handle.
        // FirstGuard 持有操作系统锁，同时另一个进程会打开并锁定独立句柄。
        let first_guard = acquire_managed_runtime_env_file_lock(&plan)
            .expect("acquire first managed environment file lock");
        let started_path = root.join("child-started");
        let acquired_path = root.join("child-acquired");
        let current_test_executable =
            std::env::current_exe().expect("resolve current test executable");
        let mut child = Command::new(current_test_executable)
            .arg("runtime::managed_runtime::tests::managed_runtime_environment_file_lock_child_probe")
            .arg("--exact")
            .arg("--nocapture")
            .env("LUASKILLS_TEST_ENV_LOCK_ROOT", &root)
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .spawn()
            .expect("spawn cross-process file-lock probe");
        // Full-suite process pressure can delay test-binary startup substantially on Windows CI.
        // Windows CI 全量测试的进程压力可能显著延迟测试二进制启动。
        let start_deadline = std::time::Instant::now() + Duration::from_secs(60);
        while !started_path.exists() && std::time::Instant::now() < start_deadline {
            thread::sleep(Duration::from_millis(10));
        }
        assert!(started_path.exists(), "child lock probe must start");
        thread::sleep(Duration::from_millis(150));
        assert!(
            !acquired_path.exists(),
            "child process must block while the parent lock is held"
        );
        drop(first_guard);
        let exit_deadline = std::time::Instant::now() + Duration::from_secs(10);
        let status = loop {
            if let Some(status) = child.try_wait().expect("poll file-lock child") {
                break status;
            }
            if std::time::Instant::now() >= exit_deadline {
                let _ = child.kill();
                let reap_deadline = std::time::Instant::now() + Duration::from_secs(5);
                while child.try_wait().ok().flatten().is_none()
                    && std::time::Instant::now() < reap_deadline
                {
                    thread::sleep(Duration::from_millis(10));
                }
                panic!("file-lock child did not finish after parent released the lock");
            }
            thread::sleep(Duration::from_millis(10));
        };
        assert!(status.success(), "file-lock child failed: {status}");
        assert!(
            acquired_path.exists(),
            "child must acquire the released lock"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Child-process probe that retains one shared environment lifecycle lease until released.
    /// 子进程探针，会保留一个共享环境生命周期租约直至收到释放信号。
    #[test]
    fn managed_runtime_environment_lifecycle_lease_child_probe() {
        // Root is present only when the parent cross-process lifecycle test launches this probe.
        // Root 仅在父级跨进程生命周期测试启动当前探针时存在。
        let Some(root) = std::env::var_os("LUASKILLS_TEST_ENV_LEASE_ROOT") else {
            return;
        };
        // RootPath identifies the exact ready environment and synchronization files.
        // RootPath 标识精确就绪环境与同步文件。
        let root = PathBuf::from(root);
        // Plan matches the parent process environment identity exactly.
        // Plan 与父进程环境身份完全匹配。
        let plan = make_environment_file_lock_test_plan(&root);
        // Lease is retained until the parent explicitly permits process exit.
        // Lease 会保留到父进程显式允许当前进程退出为止。
        let lease = acquire_ready_managed_env_lease(&plan)
            .expect("child acquires shared managed environment lifecycle lease");
        // AcquiredPath publishes that the operating-system shared lock is already held.
        // AcquiredPath 发布操作系统共享锁已经持有这一事实。
        let acquired_path = root.join("lease-acquired");
        fs::write(&acquired_path, b"acquired").expect("write lifecycle lease acquisition signal");
        // ReleasePath is created by the parent after it observes the expected busy result.
        // ReleasePath 会在父进程观察到预期 busy 结果后由父进程创建。
        let release_path = root.join("lease-release");
        // Deadline prevents one failed parent from leaving the child probe alive indefinitely.
        // Deadline 防止失败的父进程让子探针无限期存活。
        let deadline = std::time::Instant::now() + Duration::from_secs(60);
        while !release_path.exists() && std::time::Instant::now() < deadline {
            thread::sleep(Duration::from_millis(10));
        }
        assert!(
            release_path.exists(),
            "parent must release lifecycle lease probe"
        );
        drop(lease);
    }

    /// Verify a cross-process shared lifecycle lease blocks replacement until it is released.
    /// 验证跨进程共享生命周期租约会阻止替换，直至该租约被释放。
    #[test]
    fn managed_runtime_environment_lifecycle_lease_guards_publication() {
        // Root isolates the published environment, replacement build, lease file, and child signals.
        // Root 隔离已发布环境、替换构建、租约文件及子进程信号。
        let root = make_test_root("cross-process-env-lifecycle-lease");
        fs::create_dir_all(&root).expect("create lifecycle lease test root");
        // Plan supplies one stable environment identity shared with the child probe.
        // Plan 提供与子探针共享的稳定环境身份。
        let plan = make_environment_file_lock_test_plan(&root);
        fs::create_dir_all(&plan.env_dir).expect("create published lifecycle test environment");
        write_expected_marker(&plan.env_dir, &plan.expected_marker)
            .expect("write published lifecycle test marker");
        // OldMarker proves the active published environment remains untouched after a busy result.
        // OldMarker 证明返回 busy 后活动的已发布环境保持未被修改。
        let old_marker = plan.env_dir.join("old-environment");
        fs::write(&old_marker, b"old").expect("write old environment marker");
        // BuildDir is the complete unpublished replacement reused after lease release.
        // BuildDir 是在租约释放后复用的完整未发布替换目录。
        let build_dir = root.join("replacement-build");
        fs::create_dir_all(&build_dir).expect("create lifecycle replacement build");
        // NewMarker proves the replacement becomes authoritative only after successful publication.
        // NewMarker 证明替换仅在成功发布后成为权威环境。
        let new_marker_name = "new-environment";
        fs::write(build_dir.join(new_marker_name), b"new")
            .expect("write replacement environment marker");
        // ChildExecutable is the current test binary used for a real cross-process lease owner.
        // ChildExecutable 是用于创建真实跨进程租约所有者的当前测试二进制文件。
        let child_executable = std::env::current_exe().expect("resolve lifecycle test executable");
        // Child retains the shared lease while the parent attempts nonblocking publication.
        // Child 会在父进程尝试非阻塞发布期间保留共享租约。
        let mut child = Command::new(child_executable)
            .arg(
                "runtime::managed_runtime::tests::managed_runtime_environment_lifecycle_lease_child_probe",
            )
            .arg("--exact")
            .arg("--nocapture")
            .env("LUASKILLS_TEST_ENV_LEASE_ROOT", &root)
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .spawn()
            .expect("spawn lifecycle lease child probe");
        // AcquiredPath is written only after the child owns its shared OS lock.
        // AcquiredPath 仅在子进程拥有共享操作系统锁后写入。
        let acquired_path = root.join("lease-acquired");
        // AcquireDeadline tolerates slow test-binary startup under full-suite process pressure.
        // AcquireDeadline 容忍全量测试进程压力下较慢的测试二进制启动。
        let acquire_deadline = std::time::Instant::now() + Duration::from_secs(60);
        while !acquired_path.exists() && std::time::Instant::now() < acquire_deadline {
            thread::sleep(Duration::from_millis(10));
        }
        if !acquired_path.exists() {
            let _ = child.kill();
            let _ = child.wait();
            panic!("child lifecycle lease probe must acquire its shared lock");
        }

        // BusyError proves publication is nonblocking and leaves both directories owned in place.
        // BusyError 证明发布为非阻塞操作，并让两个目录都保持原位且所有权不变。
        let busy_error = finish_build_dir(&plan, build_dir.clone())
            .expect_err("active shared lifecycle lease must block environment replacement");
        assert!(
            busy_error.contains("busy with active lifecycle leases"),
            "unexpected lifecycle lease error: {busy_error}"
        );
        assert!(old_marker.is_file());
        assert!(build_dir.join(new_marker_name).is_file());

        // ReleasePath permits the child to drop its shared lease before the second publication.
        // ReleasePath 允许子进程在第二次发布前释放其共享租约。
        let release_path = root.join("lease-release");
        fs::write(&release_path, b"release").expect("release lifecycle lease child probe");
        // ExitDeadline bounds child shutdown after its lease is released.
        // ExitDeadline 限制子进程释放租约后的退出等待时长。
        let exit_deadline = std::time::Instant::now() + Duration::from_secs(10);
        // ChildStatus is captured only after definitive child exit.
        // ChildStatus 仅在子进程确定退出后捕获。
        let child_status = loop {
            if let Some(status) = child.try_wait().expect("poll lifecycle lease child") {
                break status;
            }
            if std::time::Instant::now() >= exit_deadline {
                let _ = child.kill();
                let _ = child.wait();
                panic!("lifecycle lease child did not finish after release");
            }
            thread::sleep(Duration::from_millis(10));
        };
        assert!(
            child_status.success(),
            "lifecycle lease child failed: {child_status}"
        );

        finish_build_dir(&plan, build_dir)
            .expect("environment replacement succeeds after shared lease release");
        assert!(plan.env_dir.join(new_marker_name).is_file());
        assert!(!plan.env_dir.join("old-environment").exists());
        let _ = fs::remove_dir_all(root);
    }

    /// Verify committed publication succeeds while obsolete-backup deletion retries durably.
    /// 验证已提交发布会成功返回，同时持久重试过时备份删除。
    #[test]
    fn managed_runtime_committed_backup_cleanup_failure_is_retried() {
        // Root and Plan isolate one published environment plus its complete replacement build.
        // Root 与 Plan 隔离单个已发布环境及其完整替换构建。
        let root = make_test_root("committed-backup-cleanup-retry");
        fs::create_dir_all(&root).expect("create committed backup retry root");
        let plan = make_environment_file_lock_test_plan(&root);
        fs::create_dir_all(&plan.env_dir).expect("create old managed environment");
        fs::write(plan.env_dir.join("old-environment"), b"old")
            .expect("write old managed environment evidence");
        let build_dir = root.join("replacement-build");
        fs::create_dir(&build_dir).expect("create replacement build directory");
        fs::write(build_dir.join("new-environment"), b"new")
            .expect("write new managed environment evidence");
        // CapturedBackup receives the exact identity-bound path handed to the retry worker.
        // CapturedBackup 接收移交给重试 Worker 的精确身份绑定路径。
        let captured_backup = Arc::new(Mutex::new(None::<PathBuf>));
        let captured_backup_for_remover = Arc::clone(&captured_backup);

        let result = finish_build_dir_with_backup_remover(
            &plan,
            build_dir,
            move |backup_path, _identity| {
                *captured_backup_for_remover
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner) =
                    Some(backup_path.to_path_buf());
                Err("forced obsolete-backup removal failure".to_string())
            },
        );

        assert!(
            result.is_ok(),
            "committed publication must remain successful"
        );
        assert!(plan.env_dir.join("new-environment").is_file());
        assert!(!plan.env_dir.join("old-environment").exists());
        let backup_path = captured_backup
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .clone()
            .expect("capture committed backup retry path");
        // Deadline bounds the persistent worker while tolerating full-suite scheduling pressure.
        // Deadline 限制持久 Worker 等待时间，同时容忍全量测试调度压力。
        let deadline = std::time::Instant::now() + Duration::from_secs(5);
        while backup_path.exists() && std::time::Instant::now() < deadline {
            thread::sleep(Duration::from_millis(10));
        }
        assert!(
            !backup_path.exists(),
            "persistent recovery worker must delete the obsolete backup"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify an immediate cleanup panic cannot lose the committed backup recovery record.
    /// 验证即时清理 panic 不会丢失已提交备份的恢复记录。
    #[test]
    fn managed_runtime_committed_backup_cleanup_panic_is_retried() {
        // Root and Plan isolate one replacement whose immediate remover panics after capture.
        // Root 与 Plan 隔离单个替换事务，其即时删除器会在捕获路径后 panic。
        let root = make_test_root("committed-backup-cleanup-panic-retry");
        fs::create_dir_all(&root).expect("create committed backup panic retry root");
        let plan = make_environment_file_lock_test_plan(&root);
        fs::create_dir_all(&plan.env_dir).expect("create old managed environment");
        fs::write(plan.env_dir.join("old-environment"), b"old")
            .expect("write old managed environment evidence");
        let build_dir = root.join("replacement-build");
        fs::create_dir(&build_dir).expect("create replacement build directory");
        fs::write(build_dir.join("new-environment"), b"new")
            .expect("write new managed environment evidence");
        // CapturedBackup proves the panicking call operated on the exact retained backup path.
        // CapturedBackup 证明 panic 调用操作的是精确保留备份路径。
        let captured_backup = Arc::new(Mutex::new(None::<PathBuf>));
        let captured_backup_for_remover = Arc::clone(&captured_backup);

        let result = finish_build_dir_with_backup_remover(
            &plan,
            build_dir,
            move |backup_path, _identity| {
                *captured_backup_for_remover
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner) =
                    Some(backup_path.to_path_buf());
                panic!("forced obsolete-backup cleanup panic");
            },
        );

        assert!(
            result.is_ok(),
            "committed publication must survive immediate cleanup panic"
        );
        assert!(plan.env_dir.join("new-environment").is_file());
        assert!(!plan.env_dir.join("old-environment").exists());
        let backup_path = captured_backup
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .clone()
            .expect("capture committed backup panic retry path");
        // Deadline bounds the durable retry after the panic is isolated.
        // Deadline 限制 panic 被隔离后的持久重试等待时间。
        let deadline = std::time::Instant::now() + Duration::from_secs(5);
        while backup_path.exists() && std::time::Instant::now() < deadline {
            thread::sleep(Duration::from_millis(10));
        }
        assert!(
            !backup_path.exists(),
            "persistent recovery worker must delete the backup retained across panic"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify a retained failed-publication record restores its exact old directory object.
    /// 验证已保留的失败发布记录会恢复其精确旧目录对象。
    #[test]
    fn managed_runtime_failed_publication_backup_is_restored() {
        // Plan target starts absent while Backup owns the old environment object and evidence.
        // Plan 目标初始不存在，Backup 拥有旧环境对象及证据。
        let root = make_test_root("failed-publication-backup-restore");
        fs::create_dir_all(&root).expect("create failed publication recovery root");
        let plan = make_environment_file_lock_test_plan(&root);
        let env_parent = plan.env_dir.parent().expect("managed env parent");
        fs::create_dir_all(env_parent).expect("create managed env parent");
        let backup_path = env_parent.join(".replaced-restore-test");
        fs::create_dir(&backup_path).expect("create failed publication backup");
        fs::write(backup_path.join("old-environment"), b"old")
            .expect("write failed publication backup evidence");
        let identity = capture_managed_directory_identity(
            &fs::canonicalize(&backup_path).expect("canonicalize failed publication backup"),
            "test failed publication backup",
        )
        .expect("capture failed publication backup identity");
        let canonical_backup = fs::canonicalize(&backup_path)
            .expect("retain canonical failed publication backup path");
        let (recovery_center, recovery_permit) = reserve_managed_runtime_backup_recovery_slot()
            .expect("reserve failed publication recovery slot");
        recovery_center.enqueue(ManagedRuntimeBackupRecoveryRecord {
            backup_path: canonical_backup,
            identity,
            action: ManagedRuntimeBackupRecoveryAction::RestoreFailedPublication {
                plan: Box::new(plan.clone()),
            },
            _permit: recovery_permit,
            error_reported: false,
        });

        // Deadline bounds the worker restore and verifies the old object returns under env_dir.
        // Deadline 限制 Worker 恢复时间，并验证旧对象返回 env_dir 名称下。
        let deadline = std::time::Instant::now() + Duration::from_secs(5);
        while !plan.env_dir.exists() && std::time::Instant::now() < deadline {
            thread::sleep(Duration::from_millis(10));
        }
        assert!(plan.env_dir.join("old-environment").is_file());
        assert!(!backup_path.exists());
        let _ = fs::remove_dir_all(root);
    }

    /// Verify build preparation skips a stale file collision and atomically creates a new candidate.
    /// 验证构建准备会跳过陈旧文件碰撞，并原子创建一个新候选目录。
    #[test]
    fn prepare_build_dir_skips_stale_file_collision() {
        // Temporary root that isolates the file-backed build directory fixture.
        // 隔离文件型构建目录夹具的临时根目录。
        let root = make_test_root("file-build-dir");
        fs::create_dir_all(&root).expect("create file-backed build directory root");
        // ManagedRuntimeRoots supplies a real identity-pinned authority for the synthetic plan.
        // ManagedRuntimeRoots 为合成计划提供真实固定身份授权。
        let managed_runtime_roots = Arc::new(
            ManagedRuntimeRoots::new(&root, Some(&root), Some(&root))
                .expect("create build-directory test managed runtime roots"),
        );
        // Reproducibility input used to build the expected marker for this synthetic plan.
        // 用于为这个合成计划构造期望标记的可复现输入。
        let hash_input = ManagedRuntimeEnvHashInput {
            runtime: ManagedRuntimeKind::Python,
            runtime_version: "3.14.4".to_string(),
            platform: "test-platform".to_string(),
            package_manager: "uv".to_string(),
            package_manager_version: "0.11.28".to_string(),
            lock_hash: "lock".to_string(),
            package_manifest_hash: None,
            runtime_install_manifest_hash: "python-manifest".to_string(),
            runtime_executable_hash: "python-executable".to_string(),
            package_manager_install_manifest_hash: "uv-manifest".to_string(),
            package_manager_executable_hash: "uv-executable".to_string(),
        };
        // Fixed environment hash that lets the test occupy the exact derived build directory.
        // 固定环境哈希，便于测试占用精确派生出的构建目录。
        let env_hash = "file-build-hash".to_string();
        // Expected marker matching the synthetic environment plan.
        // 与合成环境计划匹配的期望标记。
        let expected_marker = ManagedRuntimeEnvMarker::expected(&hash_input, env_hash.clone());
        // Environment plan whose candidate directory is deterministic under the injected sequence.
        // 在注入序号下具有确定候选目录的环境计划。
        let plan = ManagedRuntimeEnvPlan {
            runtime: ManagedRuntimeKind::Python,
            platform: hash_input.platform.clone(),
            runtime_root: root.clone(),
            distribution_root: root.clone(),
            environment_root: root.clone(),
            distribution_source: ManagedRuntimeRootSource::HostConfigured,
            environment_source: ManagedRuntimeRootSource::HostConfigured,
            runtime_install_root: root.join("python-install"),
            runtime_version: hash_input.runtime_version.clone(),
            runtime_executable: PathBuf::from("python"),
            runtime_install_manifest_hash: hash_input.runtime_install_manifest_hash.clone(),
            runtime_executable_hash: hash_input.runtime_executable_hash.clone(),
            package_manager: hash_input.package_manager.clone(),
            package_manager_version: hash_input.package_manager_version.clone(),
            package_manager_executable: PathBuf::from("uv"),
            package_manager_install_root: root.join("uv-install"),
            package_manager_install_manifest_hash: hash_input
                .package_manager_install_manifest_hash
                .clone(),
            package_manager_executable_hash: hash_input.package_manager_executable_hash.clone(),
            managed_runtime_roots,
            package_manifest_path: None,
            lockfile_path: root.join("requirements.lock"),
            lock_hash: hash_input.lock_hash.clone(),
            package_manifest_hash: None,
            env_hash: env_hash.clone(),
            env_dir: root.join("env"),
            expected_marker,
        };
        // First deterministic candidate occupied by a stale regular file from an interrupted build.
        // 被中断构建留下的陈旧普通文件占据的第一个确定候选路径。
        let stale_build_path =
            root.join(format!(".building-{}-{}-17", env_hash, std::process::id()));
        fs::write(&stale_build_path, b"stale build marker")
            .expect("stale build file should be written");
        // Deterministic candidate suffixes proving the allocator advances after AlreadyExists.
        // 用于证明遇到 AlreadyExists 后分配器会继续前进的确定候选后缀。
        let mut sequences = [17_u64, 18_u64].into_iter();

        // Fresh directory returned after the stale file candidate is skipped without deletion.
        // 跳过陈旧文件候选且不删除它之后返回的新目录。
        let build_dir = prepare_build_dir_with_sequence(&plan, || {
            sequences
                .next()
                .ok_or_else(|| "test build sequence exhausted".to_string())
        })
        .expect("stale build file collision should be skipped");
        let expected_build_dir =
            root.join(format!(".building-{}-{}-18", env_hash, std::process::id()));

        assert_eq!(build_dir, expected_build_dir);
        assert!(build_dir.is_dir());
        assert_eq!(
            fs::read(&stale_build_path).expect("read preserved stale build file"),
            b"stale build marker"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify copy fallback rejects symlink entries instead of following them.
    /// 验证复制降级会拒绝符号链接目录项，而不是跟随它们。
    #[test]
    fn copy_dir_recursive_rejects_symlink_entry() {
        // Temporary root that isolates the symlink copy fixture.
        // 隔离符号链接复制夹具的临时根目录。
        let root = make_test_root("copy-symlink-entry");
        // Source build directory consumed by the recursive copy fallback.
        // 递归复制降级使用的源构建目录。
        let source_dir = root.join("source");
        // Destination env directory consumed by the recursive copy fallback.
        // 递归复制降级使用的目标环境目录。
        let destination_dir = root.join("destination");
        fs::create_dir_all(&source_dir).expect("copy source dir should be created");
        // Real file target used only to create the symlink fixture.
        // 仅用于创建符号链接夹具的真实文件目标。
        let real_file_path = root.join("real-handler.py");
        fs::write(&real_file_path, b"print('ok')").expect("real file should be written");
        // Symlink entry inside the source build directory.
        // 源构建目录内的符号链接目录项。
        let symlink_path = source_dir.join("handler-link.py");
        if !create_test_file_symlink(&symlink_path, &real_file_path) {
            let _ = fs::remove_dir_all(root);
            return;
        }

        // Error returned before the symlink source entry can be silently followed.
        // 在符号链接源目录项被静默跟随之前返回的错误。
        let error = copy_dir_recursive(&source_dir, &destination_dir)
            .expect_err("symlink entry should fail managed runtime copy");

        assert!(
            error.contains("unsupported file type"),
            "unexpected error: {}",
            error
        );
        assert!(
            error.contains(&render_host_visible_path(&symlink_path)),
            "unexpected error: {}",
            error
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify copy fallback rejects unsupported Unix filesystem entry types explicitly.
    /// 验证复制降级会显式拒绝不支持的 Unix 文件系统目录项类型。
    #[cfg(unix)]
    #[test]
    fn copy_dir_recursive_rejects_unsupported_unix_file_type() {
        use std::os::unix::fs::FileTypeExt;

        // Temporary root that isolates the unsupported-file-type copy fixture.
        // 隔离不支持文件类型复制夹具的临时根目录。
        let root = make_test_root("copy-unsupported-type");
        // Source build directory consumed by the recursive copy fallback.
        // 递归复制降级使用的源构建目录。
        let source_dir = root.join("source");
        // Destination env directory consumed by the recursive copy fallback.
        // 递归复制降级使用的目标环境目录。
        let destination_dir = root.join("destination");
        fs::create_dir_all(&source_dir).expect("copy source dir should be created");
        // FIFO path that is neither a regular file nor a directory.
        // 既不是普通文件也不是目录的 FIFO 路径。
        let fifo_path = source_dir.join("events.pipe");
        // Command status returned by mkfifo for the FIFO fixture creation.
        // mkfifo 为创建 FIFO 夹具返回的命令状态。
        let status = std::process::Command::new("mkfifo")
            .arg(&fifo_path)
            .status()
            .expect("mkfifo should run");
        assert!(status.success(), "mkfifo should create FIFO fixture");
        assert!(
            fs::metadata(&fifo_path)
                .expect("FIFO metadata should be readable")
                .file_type()
                .is_fifo(),
            "fixture should be FIFO"
        );

        // Error returned before the unsupported entry can reach fs::copy.
        // 在不支持的目录项进入 fs::copy 之前返回的错误。
        let error = copy_dir_recursive(&source_dir, &destination_dir)
            .expect_err("unsupported FIFO entry should fail managed runtime copy");

        assert!(
            error.contains("unsupported file type"),
            "unexpected error: {}",
            error
        );
        assert!(
            error.contains(&render_host_visible_path(&fifo_path)),
            "unexpected error: {}",
            error
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify that Python environment plans resolve runtime manifests, lockfiles, and env markers.
    /// 验证 Python 环境计划会解析运行时清单、锁文件与环境标记。
    #[test]
    fn python_env_plan_resolves_manifests_and_lockfile() {
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        let root = make_test_root("python-plan");
        let runtime_root = root.join("runtime");
        let package_root = root.join("skill");
        fs::create_dir_all(package_root.join("python")).unwrap();
        fs::write(
            package_root.join("python/requirements.lock"),
            b"requests==2.32.3",
        )
        .unwrap();
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("cpython-3.14.4-{}", platform)),
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );

        let package = make_test_package_context(&package_root, &runtime_root);
        let plan = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "python/requirements.lock".to_string(),
                required: true,
            },
        )
        .expect("python env plan should resolve");

        assert_eq!(plan.runtime, ManagedRuntimeKind::Python);
        assert_eq!(plan.package_manager, "uv");
        assert_eq!(plan.lock_hash, sha256_hex(b"requests==2.32.3"));
        assert_eq!(plan.expected_marker.env_hash, plan.env_hash);
        assert!(
            plan.env_dir
                .starts_with(package.runtime_root().join("dependencies/envs/python"))
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify directory executables are reported as type errors instead of missing executables.
    /// 验证目录型 executable 会被报告为类型错误，而不是缺失可执行文件。
    #[test]
    fn python_env_plan_rejects_directory_runtime_executable() {
        // Platform key used to create matching runtime install manifests.
        // 用于创建匹配运行时安装清单的平台键。
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        // Temporary root that isolates the directory executable fixture.
        // 隔离目录型 executable 夹具的临时根目录。
        let root = make_test_root("directory-runtime-executable");
        // Runtime root containing the fake installed runtime manifests.
        // 包含伪造已安装运行时清单的运行时根目录。
        let runtime_root = root.join("runtime");
        // Package directory containing the Python lockfile fixture.
        // 包含 Python lockfile 夹具的包目录。
        let package_root = root.join("skill");
        fs::create_dir_all(package_root.join("python")).unwrap();
        fs::write(
            package_root.join("python/requirements.lock"),
            b"requests==2.32.3",
        )
        .unwrap();
        // Python runtime install directory whose manifest executable path is occupied by a directory.
        // 其清单 executable 路径被目录占据的 Python 运行时安装目录。
        let python_install_dir = runtime_root
            .join("dependencies")
            .join("runtimes")
            .join("python")
            .join(format!("cpython-3.14.4-{}", platform));
        // Manifest-declared executable path that must be a file.
        // 清单声明且必须为文件的 executable 路径。
        let executable_path = python_install_dir.join(platform_executable("python"));
        fs::create_dir_all(&executable_path).expect("directory executable should be created");
        // Runtime manifest declaring the directory-backed executable path.
        // 声明目录型 executable 路径的运行时清单。
        let payload = serde_json::json!({
            "schema_version": 1,
            "runtime": "python",
            "version": "3.14.4",
            "platform": platform,
            "executable": platform_executable("python"),
        });
        fs::write(
            python_install_dir.join("runtime-manifest.json"),
            serde_json::to_string_pretty(&payload).unwrap(),
        )
        .unwrap();
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );

        // Error returned by the full Python environment plan resolver.
        // 完整 Python 环境计划解析器返回的错误。
        let package = make_test_package_context(&package_root, &runtime_root);
        let error = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "python/requirements.lock".to_string(),
                required: true,
            },
        )
        .expect_err("directory runtime executable should be rejected");
        // Error text expected from the shared host-visible path formatter.
        // 由共享宿主可见路径渲染器生成的期望错误文本。
        // Canonical directory path matching the production resolver diagnostic.
        // 与生产解析器诊断一致的规范目录路径。
        let canonical_executable_path = fs::canonicalize(&executable_path)
            .expect("canonicalize directory runtime executable fixture");
        let expected_error = format!(
            "managed runtime distribution source=runtime_root_default: managed runtime executable is not a file: {}",
            render_host_visible_path(&canonical_executable_path)
        );

        assert_eq!(error, expected_error);
        // Cleanup result is intentionally ignored for best-effort temporary test artifacts.
        // 对临时测试产物的清理结果按最佳努力原则有意忽略。
        let _ = fs::remove_dir_all(root);
    }

    /// Verify that Node environment plans include package.json in the environment identity.
    /// 验证 Node 环境计划会把 package.json 纳入环境身份。
    #[test]
    fn node_env_plan_includes_package_manifest_hash() {
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        let root = make_test_root("node-plan");
        let runtime_root = root.join("runtime");
        let package_root = root.join("skill");
        fs::create_dir_all(package_root.join("node")).unwrap();
        fs::write(
            package_root.join("node/package.json"),
            br#"{"dependencies":{}}"#,
        )
        .unwrap();
        fs::write(
            package_root.join("node/pnpm-lock.yaml"),
            b"lockfileVersion: '9.0'",
        )
        .unwrap();
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/node")
                .join(format!("node-24.18.0-{}", platform)),
            "node",
            "24.18.0",
            &platform,
            platform_executable("node"),
        );
        write_install_manifest(
            &runtime_root.join("dependencies/runtimes/node/pnpm-11.11.0"),
            "pnpm",
            "11.11.0",
            "any",
            "bin/pnpm.cjs",
        );

        let package = make_test_package_context(&package_root, &runtime_root);
        let plan = resolve_node_env_plan(
            package.as_ref(),
            &NodeRuntimeDependencySpec {
                version: "24.18.0".to_string(),
                package_manager: NodeRuntimePackageManager::Pnpm,
                package_manager_version: "11.11.0".to_string(),
                package_json: "node/package.json".to_string(),
                lockfile: "node/pnpm-lock.yaml".to_string(),
                required: true,
            },
        )
        .expect("node env plan should resolve");

        assert_eq!(plan.runtime, ManagedRuntimeKind::Node);
        assert_eq!(plan.package_manager, "pnpm");
        assert_eq!(plan.lock_hash, sha256_hex(b"lockfileVersion: '9.0'"));
        assert_eq!(
            plan.package_manifest_hash,
            Some(sha256_hex(br#"{"dependencies":{}}"#))
        );
        assert!(
            plan.env_dir
                .starts_with(package.runtime_root().join("dependencies/envs/node"))
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify Node environment planning rejects EOL runtimes before any installation lookup.
    /// 验证 Node 环境规划会在任何安装查找前拒绝已终止维护的运行时。
    #[test]
    fn node_env_plan_rejects_runtime_older_than_supported_esm_baseline() {
        // Root owns a real trusted package context while intentionally containing no runtime assets.
        // Root 拥有真实可信包上下文，同时有意不包含任何运行时资产。
        let root = make_test_root("unsupported-node-runtime-version");
        let runtime_root = root.join("runtime");
        let package_root = root.join("skill");
        let package = make_test_package_context(&package_root, &runtime_root);
        let error = resolve_node_env_plan(
            package.as_ref(),
            &NodeRuntimeDependencySpec {
                version: "18.19.1".to_string(),
                package_manager: NodeRuntimePackageManager::Pnpm,
                package_manager_version: "11.11.0".to_string(),
                package_json: "node/package.json".to_string(),
                lockfile: "node/pnpm-lock.yaml".to_string(),
                required: true,
            },
        )
        .expect_err("pre-22 Node runtime must be rejected before installation lookup");

        assert_eq!(
            error,
            "managed Node runtime 18.19.1 is unsupported; minimum supported version is 22.0.0"
        );
        let _ = fs::remove_dir_all(root);
    }

    /// Verify malformed Node versions fail as declarations rather than filesystem errors.
    /// 验证格式错误的 Node 版本会作为声明错误失败，而不是文件系统错误。
    #[test]
    fn node_env_plan_rejects_non_semantic_runtime_version() {
        let root = make_test_root("invalid-node-runtime-version");
        let runtime_root = root.join("runtime");
        let package_root = root.join("skill");
        let package = make_test_package_context(&package_root, &runtime_root);
        let error = resolve_node_env_plan(
            package.as_ref(),
            &NodeRuntimeDependencySpec {
                version: "current".to_string(),
                package_manager: NodeRuntimePackageManager::Pnpm,
                package_manager_version: "11.11.0".to_string(),
                package_json: "node/package.json".to_string(),
                lockfile: "node/pnpm-lock.yaml".to_string(),
                required: true,
            },
        )
        .expect_err("non-semantic Node runtime version must be rejected");

        assert!(error.starts_with("node_runtime.version is not valid semantic version 'current':"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify that managed runtime declarations cannot escape the package root.
    /// 验证受管运行时声明不能逃逸包根目录。
    #[test]
    fn managed_runtime_plan_rejects_package_path_traversal() {
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        let root = make_test_root("path-traversal");
        let runtime_root = root.join("runtime");
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("cpython-3.14.4-{}", platform)),
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );
        let package_root = root.join("skill");
        let package = make_test_package_context(&package_root, &runtime_root);
        let error = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "../outside.lock".to_string(),
                required: true,
            },
        )
        .expect_err("path traversal should be rejected");

        assert!(error.contains("safe path under the package root"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify that missing lockfile errors render paths through the host-visible path formatter.
    /// 验证缺失锁文件错误会通过宿主可见路径渲染器输出路径。
    #[test]
    fn python_env_plan_missing_lockfile_error_uses_host_visible_path() {
        // Platform key used to create matching runtime install manifests.
        // 用于创建匹配运行时安装清单的平台键。
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        // Temporary root that isolates all filesystem fixtures for this test.
        // 隔离当前测试所有文件系统夹具的临时根目录。
        let root = make_test_root("missing-lockfile-path");
        // Runtime root containing the fake installed runtime manifests.
        // 包含伪造已安装运行时清单的运行时根目录。
        let runtime_root = root.join("runtime");
        // Package directory used as the base for the missing relative lockfile.
        // 作为缺失相对锁文件基准目录的包目录。
        let package_root = root.join("skill");
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("cpython-3.14.4-{}", platform)),
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );

        // Error returned by the full Python environment plan resolver.
        // 完整 Python 环境计划解析器返回的错误。
        let package = make_test_package_context(&package_root, &runtime_root);
        // Native-separator candidate derived from the canonical trusted package root.
        // 从规范可信包根派生的原生分隔符候选路径。
        let expected_lockfile = package.package_root().join("python").join("missing.lock");
        let error = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "python/missing.lock".to_string(),
                required: true,
            },
        )
        .expect_err("missing lockfile should be reported");
        assert!(
            error.contains("failed to canonicalize python_runtime.lockfile"),
            "unexpected error: {error}"
        );
        assert!(
            error.contains(&render_host_visible_path(&expected_lockfile)),
            "unexpected error: {error}"
        );
        // Cleanup result is intentionally ignored for best-effort temporary test artifacts.
        // 对临时测试产物的清理结果按最佳努力原则有意忽略。
        let _ = fs::remove_dir_all(root);
    }

    /// Verify directory lockfiles are reported as type errors instead of missing files.
    /// 验证目录型 lockfile 会被报告为类型错误，而不是缺失文件。
    #[test]
    fn python_env_plan_rejects_directory_lockfile() {
        // Platform key used to create matching runtime install manifests.
        // 用于创建匹配运行时安装清单的平台键。
        let platform = current_managed_runtime_platform_key().expect("platform should resolve");
        // Temporary root that isolates the directory lockfile fixture.
        // 隔离目录型 lockfile 夹具的临时根目录。
        let root = make_test_root("directory-lockfile");
        // Runtime root containing the fake installed runtime manifests.
        // 包含伪造已安装运行时清单的运行时根目录。
        let runtime_root = root.join("runtime");
        // Package directory used as the base for the directory lockfile.
        // 作为目录型 lockfile 基准目录的包目录。
        let package_root = root.join("skill");
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("cpython-3.14.4-{}", platform)),
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &runtime_root
                .join("dependencies/runtimes/python")
                .join(format!("uv-0.11.28-{}", platform)),
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );
        // Directory occupying the lockfile path declared by the Python runtime dependency.
        // 占据 Python 运行时依赖声明 lockfile 路径的目录。
        let lockfile_path = package_root.join("python/requirements.lock");
        fs::create_dir_all(&lockfile_path).expect("directory lockfile should be created");

        // Error returned by the full Python environment plan resolver.
        // 完整 Python 环境计划解析器返回的错误。
        let package = make_test_package_context(&package_root, &runtime_root);
        let error = resolve_python_env_plan(
            package.as_ref(),
            &PythonRuntimeDependencySpec {
                version: "3.14.4".to_string(),
                package_manager: PythonRuntimePackageManager::Uv,
                package_manager_version: "0.11.28".to_string(),
                lockfile: "python/requirements.lock".to_string(),
                required: true,
            },
        )
        .expect_err("directory lockfile should be rejected");
        // Error text expected from the shared host-visible path formatter.
        // 由共享宿主可见路径渲染器生成的期望错误文本。
        // Canonical directory path matching the production resolver diagnostic.
        // 与生产解析器诊断一致的规范目录路径。
        let canonical_lockfile_path =
            fs::canonicalize(&lockfile_path).expect("canonicalize directory lockfile fixture");
        let expected_error = format!(
            "python_runtime.lockfile is not a file: {}",
            render_host_visible_path(&canonical_lockfile_path)
        );

        assert_eq!(error, expected_error);
        // Cleanup result is intentionally ignored for best-effort temporary test artifacts.
        // 对临时测试产物的清理结果按最佳努力原则有意忽略。
        let _ = fs::remove_dir_all(root);
    }

    /// Verify explicit host roots outside the LuaSkills data root drive Python planning and identity.
    /// 验证 LuaSkills 数据根外的显式宿主根会驱动 Python 计划与身份。
    #[test]
    fn explicit_host_roots_drive_python_plan_and_asset_invalidation() {
        // Root separates the data, read-only distribution, writable environment, and package trees.
        // Root 分离数据、只读发行、可写环境及包目录树。
        let root = make_test_root("explicit-host-roots");
        let runtime_root = root.join("运行时 数据");
        let distribution_root = root.join("应用 资产").join("runtimes");
        let environment_root = root.join("用户 数据").join("managed runtime envs");
        let package_root = root.join("插件 包");
        fs::create_dir_all(&runtime_root).expect("create explicit data root");
        fs::create_dir_all(package_root.join("python")).expect("create explicit package root");
        fs::write(
            package_root.join("python/requirements.lock"),
            b"requests==2.32.3",
        )
        .expect("write explicit Python lockfile");
        let platform = current_managed_runtime_platform_key().expect("resolve native platform");
        let runtime_install_root = distribution_root
            .join("python")
            .join(format!("cpython-3.14.4-{platform}"));
        let package_manager_install_root = distribution_root
            .join("python")
            .join(format!("uv-0.11.28-{platform}"));
        write_install_manifest(
            &runtime_install_root,
            "python",
            "3.14.4",
            &platform,
            platform_executable("python"),
        );
        write_install_manifest(
            &package_manager_install_root,
            "uv",
            "0.11.28",
            &platform,
            platform_executable("uv"),
        );
        // ManagedRuntimeRoots must preserve both explicit roots rather than deriving legacy paths.
        // ManagedRuntimeRoots 必须保留两个显式根，而不是派生旧路径。
        let managed_runtime_roots = Arc::new(
            ManagedRuntimeRoots::new(
                &runtime_root,
                Some(&distribution_root),
                Some(&environment_root),
            )
            .expect("build explicit managed runtime roots"),
        );
        let package = ManagedRuntimePackageContext::for_skill_with_roots(
            "explicit-host-roots",
            &package_root,
            Arc::clone(&managed_runtime_roots),
            None,
        )
        .expect("build explicit-root package context");
        let spec = PythonRuntimeDependencySpec {
            version: "3.14.4".to_string(),
            package_manager: PythonRuntimePackageManager::Uv,
            package_manager_version: "0.11.28".to_string(),
            lockfile: "python/requirements.lock".to_string(),
            required: true,
        };
        let original_plan =
            resolve_python_env_plan(package.as_ref(), &spec).expect("resolve explicit Python plan");

        assert_eq!(
            original_plan.distribution_root,
            fs::canonicalize(&distribution_root).expect("canonical explicit distribution root")
        );
        assert_eq!(
            original_plan.environment_root,
            fs::canonicalize(&environment_root).expect("canonical explicit environment root")
        );
        assert_eq!(
            original_plan.distribution_source,
            ManagedRuntimeRootSource::HostConfigured
        );
        assert_eq!(
            original_plan.environment_source,
            ManagedRuntimeRootSource::HostConfigured
        );
        assert!(
            original_plan
                .runtime_executable
                .starts_with(&original_plan.distribution_root)
        );
        assert!(
            original_plan
                .env_dir
                .starts_with(original_plan.environment_root.join("python"))
        );

        // MutatedExecutable models a host asset replacement under the same version and path.
        // MutatedExecutable 模拟相同版本与路径下的宿主资产替换。
        fs::write(
            &original_plan.runtime_executable,
            b"changed executable bytes",
        )
        .expect("mutate explicit Python executable");
        let changed_plan =
            resolve_python_env_plan(package.as_ref(), &spec).expect("resolve changed Python plan");
        assert_ne!(
            original_plan.runtime_executable_hash,
            changed_plan.runtime_executable_hash
        );
        assert_ne!(original_plan.env_hash, changed_plan.env_hash);
        let identity_error = validate_managed_runtime_plan_assets(&original_plan)
            .expect_err("stale plan must reject changed executable identity");
        assert!(identity_error.contains("installation identity changed"));

        // RuntimeManifestPath identifies the exact manifest captured by the changed executable plan.
        // RuntimeManifestPath 标识已变更可执行文件计划捕获的精确清单。
        let runtime_manifest_path = changed_plan
            .runtime_install_root
            .join("runtime-manifest.json");
        // RepackedManifest preserves semantic fields while changing the distribution identity bytes.
        // RepackedManifest 保留语义字段，同时改变发行身份字节。
        let repacked_manifest = serde_json::json!({
            "schema_version": 1,
            "runtime": "python",
            "version": "3.14.4",
            "platform": platform,
            "executable": platform_executable("python"),
            "source": "repacked-test-asset",
        });
        fs::write(
            &runtime_manifest_path,
            serde_json::to_string_pretty(&repacked_manifest)
                .expect("serialize repacked Python runtime manifest"),
        )
        .expect("replace explicit Python runtime manifest bytes");
        // ManifestChangedPlan must select a fresh environment identity even at the same version/path.
        // ManifestChangedPlan 即使版本与路径相同，也必须选择新的环境身份。
        let manifest_changed_plan = resolve_python_env_plan(package.as_ref(), &spec)
            .expect("resolve manifest-changed Python plan");
        assert_ne!(
            changed_plan.runtime_install_manifest_hash,
            manifest_changed_plan.runtime_install_manifest_hash
        );
        assert_ne!(changed_plan.env_hash, manifest_changed_plan.env_hash);
        // ManifestIdentityError proves an already planned environment cannot accept replaced metadata.
        // ManifestIdentityError 证明已完成计划的环境不能接受被替换的元数据。
        let manifest_identity_error = validate_managed_runtime_plan_assets(&changed_plan)
            .expect_err("stale plan must reject changed manifest identity");
        assert!(manifest_identity_error.contains("installation identity changed"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify explicit host roots outside the LuaSkills data root also drive Node planning.
    /// 验证 LuaSkills 数据根外的显式宿主根同样会驱动 Node 计划。
    #[test]
    fn explicit_host_roots_drive_node_plan() {
        // Root separates the data, distribution, environment, and package trees.
        // Root 分离数据、发行、环境及包目录树。
        let root = make_test_root("explicit-node-host-roots");
        let runtime_root = root.join("runtime data");
        let distribution_root = root.join("application assets").join("runtimes");
        let environment_root = root.join("user data").join("managed environments");
        let package_root = root.join("system plugin");
        fs::create_dir_all(&runtime_root).expect("create explicit Node data root");
        fs::create_dir_all(package_root.join("node")).expect("create explicit Node package root");
        fs::write(
            package_root.join("node/package.json"),
            b"{\"private\":true}",
        )
        .expect("write explicit Node package manifest");
        fs::write(
            package_root.join("node/pnpm-lock.yaml"),
            b"lockfileVersion: '9.0'",
        )
        .expect("write explicit Node lockfile");
        let platform = current_managed_runtime_platform_key().expect("resolve native platform");
        let runtime_install_root = distribution_root
            .join("node")
            .join(format!("node-24.18.0-{platform}"));
        let package_manager_install_root = distribution_root.join("node").join("pnpm-11.11.0");
        write_install_manifest(
            &runtime_install_root,
            "node",
            "24.18.0",
            &platform,
            platform_executable("node"),
        );
        write_install_manifest(
            &package_manager_install_root,
            "pnpm",
            "11.11.0",
            "any",
            "bin/pnpm.cjs",
        );
        let managed_runtime_roots = Arc::new(
            ManagedRuntimeRoots::new(
                &runtime_root,
                Some(&distribution_root),
                Some(&environment_root),
            )
            .expect("build explicit Node managed runtime roots"),
        );
        let package = ManagedRuntimePackageContext::for_skill_with_roots(
            "explicit-node-host-roots",
            &package_root,
            Arc::clone(&managed_runtime_roots),
            None,
        )
        .expect("build explicit Node package context");
        let spec = NodeRuntimeDependencySpec {
            version: "24.18.0".to_string(),
            package_manager: NodeRuntimePackageManager::Pnpm,
            package_manager_version: "11.11.0".to_string(),
            package_json: "node/package.json".to_string(),
            lockfile: "node/pnpm-lock.yaml".to_string(),
            required: true,
        };
        let plan =
            resolve_node_env_plan(package.as_ref(), &spec).expect("resolve explicit Node plan");

        assert_eq!(
            plan.distribution_root,
            fs::canonicalize(&distribution_root).expect("canonical explicit Node distribution")
        );
        assert_eq!(
            plan.environment_root,
            fs::canonicalize(&environment_root).expect("canonical explicit Node environment")
        );
        assert_eq!(
            plan.distribution_source,
            ManagedRuntimeRootSource::HostConfigured
        );
        assert_eq!(
            plan.environment_source,
            ManagedRuntimeRootSource::HostConfigured
        );
        assert!(plan.runtime_executable.starts_with(&plan.distribution_root));
        assert!(plan.env_dir.starts_with(plan.environment_root.join("node")));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify the public resolver returns canonical contained paths and exact byte hashes.
    /// 验证公共解析器返回规范包含路径与精确字节哈希。
    #[test]
    fn public_managed_runtime_resolver_returns_canonical_descriptor() {
        let root = make_test_root("public-install-resolver");
        let distribution_root = root.join("shared runtimes");
        let install_root = distribution_root
            .join("node")
            .join("node-24.18.0-linux-x64");
        write_install_manifest(&install_root, "node", "24.18.0", "linux-x64", "bin/node");

        let descriptor = resolve_managed_runtime_install(
            &distribution_root,
            ManagedRuntimeKind::Node,
            "24.18.0",
            "linux-x64",
        )
        .expect("resolve public Node descriptor");
        assert_eq!(descriptor.runtime, ManagedRuntimeKind::Node);
        assert_eq!(
            descriptor.install_root,
            fs::canonicalize(&install_root).expect("canonical public install root")
        );
        assert_eq!(
            descriptor.manifest_hash,
            sha256_file(&install_root.join("runtime-manifest.json")).expect("hash public manifest")
        );
        assert_eq!(
            descriptor.executable_hash,
            sha256_file(&descriptor.executable).expect("hash public executable")
        );
        assert!(descriptor.executable.starts_with(&descriptor.install_root));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify explicit root validation rejects relative, missing, and replaced distribution roots.
    /// 验证显式根校验会拒绝相对、缺失及被替换的发行根。
    #[test]
    fn managed_runtime_roots_reject_invalid_and_replaced_distribution_roots() {
        let root = make_test_root("root-validation");
        let runtime_root = root.join("runtime");
        let distribution_root = root.join("distribution");
        let environment_root = root.join("environment");
        fs::create_dir_all(&runtime_root).expect("create root-validation data root");
        fs::create_dir_all(&distribution_root).expect("create root-validation distribution root");

        let relative_error = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(Path::new("relative-runtimes")),
            Some(&environment_root),
        )
        .expect_err("relative distribution root must fail");
        assert!(relative_error.contains("must be an absolute path"));
        // RelativeEnvironmentError proves the writable authority has the same absolute-path rule.
        // RelativeEnvironmentError 证明可写授权遵循相同的绝对路径规则。
        let relative_environment_error = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(&distribution_root),
            Some(Path::new("relative-environments")),
        )
        .expect_err("relative environment root must fail");
        assert!(relative_environment_error.contains("must be an absolute path"));
        let missing_error = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(&root.join("missing-distribution")),
            Some(&environment_root),
        )
        .expect_err("missing explicit distribution root must fail");
        assert!(missing_error.contains("failed to canonicalize"));
        // DistributionFile is an existing non-directory object that cannot become an asset root.
        // DistributionFile 是不能成为资产根的现有非目录对象。
        let distribution_file = root.join("distribution-file");
        fs::write(&distribution_file, b"not a directory").expect("write distribution file fixture");
        // DistributionFileError must be a type error without attempting any PATH fallback.
        // DistributionFileError 必须是类型错误，且不能尝试任何 PATH 回退。
        let distribution_file_error = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(&distribution_file),
            Some(&environment_root),
        )
        .expect_err("distribution file must fail");
        assert!(distribution_file_error.contains("is not a directory"));
        // EnvironmentFile is an existing non-directory object at the requested writable root path.
        // EnvironmentFile 是位于请求可写根路径上的现有非目录对象。
        let environment_file = root.join("environment-file");
        fs::write(&environment_file, b"not a directory").expect("write environment file fixture");
        // EnvironmentFileError must stop root creation before any managed environment is derived.
        // EnvironmentFileError 必须在派生任何受管环境前停止根创建。
        let environment_file_error = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(&distribution_root),
            Some(&environment_file),
        )
        .expect_err("environment file must fail");
        assert!(
            environment_file_error.contains("failed to create managed runtime environment root")
        );

        let roots = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(&distribution_root),
            Some(&environment_root),
        )
        .expect("build replace-detection roots");
        let original_distribution = root.join("original-distribution");
        fs::rename(&distribution_root, &original_distribution)
            .expect("move original distribution root");
        fs::create_dir(&distribution_root).expect("create replacement distribution root");
        let replacement_error = roots
            .validate_live_filesystem_identity()
            .expect_err("same-path distribution replacement must fail");
        assert!(replacement_error.contains("filesystem object changed"));
        let _ = fs::remove_dir_all(root);
    }

    /// Verify a same-path replacement of the writable environment root is detected independently.
    /// 验证可写环境根的同路径替换会被独立检测。
    #[test]
    fn managed_runtime_roots_reject_replaced_environment_root() {
        // Root isolates all filesystem objects involved in environment-root identity validation.
        // Root 隔离环境根身份校验涉及的全部文件系统对象。
        let root = make_test_root("environment-root-replacement");
        // RuntimeRoot is the existing LuaSkills data authority required by the root set.
        // RuntimeRoot 是根集合要求的现有 LuaSkills 数据授权。
        let runtime_root = root.join("runtime");
        // DistributionRoot is an existing read-only authority unrelated to the replacement under test.
        // DistributionRoot 是与本次替换无关的现有只读授权。
        let distribution_root = root.join("distribution");
        // EnvironmentRoot is the writable authority whose native object identity is pinned.
        // EnvironmentRoot 是其平台原生对象身份会被固定的可写授权。
        let environment_root = root.join("environment");
        fs::create_dir_all(&runtime_root).expect("create environment replacement runtime root");
        fs::create_dir_all(&distribution_root)
            .expect("create environment replacement distribution root");
        // Roots captures the environment directory object before the same path is replaced.
        // Roots 在同一路径被替换前捕获环境目录对象。
        let roots = ManagedRuntimeRoots::new(
            &runtime_root,
            Some(&distribution_root),
            Some(&environment_root),
        )
        .expect("build environment replace-detection roots");
        // OriginalEnvironment retains the first object under a different name for deterministic cleanup.
        // OriginalEnvironment 以不同名称保留首个对象，以便确定性清理。
        let original_environment = root.join("original-environment");
        fs::rename(&environment_root, &original_environment)
            .expect("move original environment root");
        fs::create_dir(&environment_root).expect("create replacement environment root");
        // ReplacementError must identify the native object mismatch rather than accepting the same path.
        // ReplacementError 必须识别平台原生对象不匹配，而不能接受相同路径。
        let replacement_error = roots
            .validate_live_filesystem_identity()
            .expect_err("same-path environment replacement must fail");
        assert!(replacement_error.contains("filesystem object changed"));
        let _ = fs::remove_dir_all(root);
    }

    /// Create a unique temporary test root.
    /// 创建一个唯一的临时测试根目录。
    fn make_test_root(label: &str) -> PathBuf {
        let root = std::env::temp_dir().join(format!(
            "luaskills-managed-runtime-{}-{}-{}",
            label,
            std::process::id(),
            unique_suffix()
        ));
        fs::create_dir_all(&root).unwrap();
        root
    }

    /// Return a simple unique suffix for temporary test paths.
    /// 返回用于临时测试路径的简单唯一后缀。
    fn unique_suffix() -> u128 {
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_nanos()
    }

    /// Write one install manifest and create its declared executable.
    /// 写入一个安装清单并创建其声明的可执行文件。
    fn write_install_manifest(
        install_dir: &Path,
        runtime: &str,
        version: &str,
        platform: &str,
        executable: &str,
    ) {
        fs::create_dir_all(
            install_dir.join(Path::new(executable).parent().unwrap_or(Path::new(""))),
        )
        .unwrap();
        fs::write(install_dir.join(executable), b"executable").unwrap();
        let payload = serde_json::json!({
            "schema_version": 1,
            "runtime": runtime,
            "version": version,
            "platform": platform,
            "executable": executable,
        });
        fs::write(
            install_dir.join("runtime-manifest.json"),
            serde_json::to_string_pretty(&payload).unwrap(),
        )
        .unwrap();
    }

    /// Return a platform-shaped executable path for install manifest tests.
    /// 返回用于安装清单测试的平台形态可执行路径。
    fn platform_executable(kind: &str) -> &'static str {
        match (std::env::consts::OS, kind) {
            ("windows", "python") => "python.exe",
            ("windows", "uv") => "uv.exe",
            ("windows", "node") => "node.exe",
            (_, "python") => "bin/python3",
            (_, "uv") => "uv",
            (_, "node") => "bin/node",
            _ => "tool",
        }
    }
}