pi_async_fs 0.1.2

//! 文件系统命名空间的运行时无关公共能力合同。
//!
//! 命名空间负责按位置创建、查询和修改文件系统对象，并负责产生目录流与
//! 已打开文件资源。它不承担已打开文件的长期内容 I/O，也不提供变化监控
//! 事件。各方法分别声明定位符、失败证据、取消边界和并发语义；实现无需
//! 绑定某个具体异步运行时。

use core::fmt;
use core::future::Future;
use core::hash::Hash;

use futures_core::stream::BoxStream;
use futures_core::Stream;

use crate::{
    AvailableSpace, CopyFailure, CopyOutcome, CreateDirectoriesFailure,
    CreateFailure, CrossProcessCreateSuccess, CrossProcessFileAuthority,
    DirectoryEntry, FileAccessMode, FileIo, FileLocator, FileMetadata,
    RemoveFailure, RenameFailure, WalkEntry, WalkOptions,
};

// 运行时无关的装箱浅层目录流。
//
// 本类型是 [`FileNamespace::DirectoryStream`] 的便捷默认值。它允许简单的
// 第三方 adapter 隐藏宏生成或分页状态机的具体类型；代价是每次建立目录流
// 至少分配一次流对象，并且每次轮询经过一次动态分派。该代价不会按目录项
// 重复产生。
//
// 对性能敏感的实现应覆盖默认关联类型，使用自己的具体流或 nightly 的
// 不透明关联类型。本别名只约束流为 `Send`，不授予 `Sync`、`Clone`、排序
// 或可重复消费语义。流一旦被消费或丢弃，就不能恢复先前的后端游标。
//
// # 生命周期与内部流适配
//
// `'a` 是流可以借用 namespace 配置的最长生命周期，不会延长任何内部引用
// 的真实寿命。内部 adapter 必须把目录句柄、分页游标、响应 buffer 和取消
// 状态拥有地移动进具体流，或者只借用确实在 `'a` 内有效的 namespace 字段；
// 不能让装箱流引用已经完成的创建 Future 栈帧或其它临时变量。
//
// 实际为 `'static` 的内部流可以安全收窄到 `'a`，但公共接口不反向要求所有
// adapter 克隆 backend 客户端来制造 `'static`。宏生成或其它 `!Unpin` 流
// 由 `Box::pin` 固定后可以进入本别名；装箱和固定都不能用来掩盖 `!Send` 或
// 生命周期不足。成功产生的 [`DirectoryEntry`] 拥有全部字段，可以独立于
// 本流和 namespace 保存。
/// 运行时无关的装箱浅层目录流。
///
/// 这是 [`FileNamespace::DirectoryStream`] 的便捷默认类型。流按需产生拥有型
/// [`DirectoryEntry`]，允许唯一消费者跨线程移动，但不承诺 `Sync`、`Clone`、
/// `Unpin`、固定顺序、快照一致性或重复消费。`'a` 是流可能借用 namespace
/// 配置的最长生命周期；已经产生的目录项不借用流。产生远端目录项时，跨线程
/// 安全性还须满足 [`crate::EntryName`] 记录的最终依赖图前置条件。
pub type BoxDirectoryStream<'a, L> =
    BoxStream<'a, pi_result::Result<DirectoryEntry<L>>>;

// 运行时无关的装箱递归目录遍历流。
//
// 本类型是 [`FileNamespace::WalkStream`] 的便捷默认值。它适合包装
// `async_stream::try_stream!`、远端分页状态机或其它难以公开命名的流。
// 每次创建流至少分配一次流对象，并在每次轮询时动态分派；该成本不会按
// 项目重复产生。性能敏感 adapter 应覆盖关联类型。
//
// 流项目拥有 [`WalkEntry`]，但流状态本身可以在 `'a` 内借用 namespace
// 配置。它只承诺 `Send` 和单消费者语义，不承诺 `Sync`、`Clone`、`Unpin`、
// `FusedStream`、遍历顺序或目录快照。
//
// 创建 Future 成功时必须把待访问目录栈、当前目录流、远端分页游标、深度
// 状态和取消所有权完整移交给内部流。`'a` 只允许它继续借用 namespace 中
// 确实存活的配置；不能借用已销毁 Future 的局部状态。实际拥有全部状态的
// `'static` 流可以收窄为 `'a`，匿名或 `!Unpin` 流则通过固定装箱适配；这些
// 转换不得绕过编译器对生命周期和 `Send` 的检查。
/// 运行时无关的装箱递归目录遍历流。
///
/// 这是 [`FileNamespace::WalkStream`] 的便捷默认类型。流按需产生拥有型
/// [`WalkEntry`]，允许唯一消费者跨线程移动，但不承诺 `Sync`、`Clone`、
/// `Unpin`、固定顺序、目录快照或重复消费。`'a` 是流可能借用 namespace
/// 配置的最长生命周期；已经产生的项目不借用流。产生远端目录项时，跨线程
/// 安全性还须满足 [`crate::EntryName`] 记录的最终依赖图前置条件。
pub type BoxWalkStream<'a, L> =
    BoxStream<'a, pi_result::Result<WalkEntry<L>>>;

// 文件系统命名空间中的管理、查询和资源创建能力。
//
// # 定位符与后端选择
//
// [`Self::Locator`] 只描述当前静态 namespace 内部的位置，不是稳定文件
// 身份，也不保存已打开句柄。默认 [`FileLocator`] 适合显式组合原生路径和
// 远端 URL 的 facade；单一后端应覆盖为 `PathBuf`、`RemoteLocator` 或自己
// 的拥有型定位符，避免接收无意义的枚举分支。
//
// # 异步流
//
// [`Self::DirectoryStream`] 与 [`Self::WalkStream`] 分别是一次浅层枚举和
// 一次递归遍历的独立、惰性、单消费者资源。创建流的 Future 与随后逐项
// 轮询的错误通道不同；精确合同由 [`Self::read_dir`] 和 [`Self::walk`]
// 声明。默认装箱类型只提供易用退路，性能敏感 adapter 可以覆盖为满足
// 相同生命周期和项目合同的具体流。
//
// # 当前能力范围
//
// 当前合同覆盖查询、目录流、创建、删除、改名、严格新建复制、资源打开和
// 显式跨进程协调。文件变化监听和替换式发布尚未进入本 trait。
/// 文件系统命名空间的运行时无关管理接口。
///
/// 该接口负责按定位符查询、枚举、创建、删除、改名、复制及打开资源；已打开
/// 文件的内容 I/O 由 [`FileIo`] 负责。`Send + Sync` 允许一个 namespace 被
/// 多个线程共享，但每个方法是否允许并发、是否互斥以及取消后的可观察状态，
/// 以该方法自己的合同为准。
///
/// 定位符只表示位置，不等于稳定文件身份。返回的元信息和目录项都是拥有型
/// 快照；目录流和遍历流是惰性、单消费者资源。所有异步方法只返回标准
/// `Future + Send`，不绑定具体异步运行时。
/// 远端枚举产生 [`crate::EntryName::Remote`] 时，本 trait 的跨线程合同还须满足
/// 该类型记录的最终依赖图前置条件。
///
/// 可报告的输入、权限、能力、冲突和 I/O 失败均通过返回值表达，不得 panic。
/// 从未轮询的 Future 不产生外部副作用；一旦不可撤销操作已经提交，取消只
/// 表示调用方停止等待，方法文档中的证据类型决定普通失败时可以证明的状态。
/// 接口不调用用户代码，也不承诺固定延迟、零分配或结果快照；本地存储和远端
/// 服务都可能带来长尾等待。
///
/// 这些方法都会观察或改变外部命名空间，因此都不是纯函数。查询方法不修改
/// 文件内容或名称，允许重复调用，但结果可能随外部状态变化；创建、删除、
/// 改名和复制不得默认视为幂等，是否可重试必须依据各自的失败证据。枚举与
/// 遍历的总工作量至少随实际产生的项目数增长，复制至少随传输字节数增长；
/// 其它操作也可能等待外部存储、分配操作状态或执行不确定时长的 I/O。
///
/// 当前进程内，涉及同一父目录条目的创建、复制目标发布、安全删除和严格改名
/// 彼此排它，冲突在产生目标副作用前立即返回而不等待；互不相关的条目不因此
/// 全局串行。普通方法不自动协调其它进程或绕过本库的原生操作，跨进程保证只
/// 来自显式协调式入口。
pub trait FileNamespace: Send + Sync {
    // 当前 namespace 接受和产生的拥有型位置值。
    //
    // 克隆只复制位置表示，不能克隆后端、连接或文件句柄。比较、排序和哈希
    // 也只比较位置表示，不能证明两个定位符是否指向同一底层文件身份。
    /// 当前 namespace 接受和产生的拥有型位置类型。
    ///
    /// 比较、排序和哈希只比较位置表示，不能证明两个值指向同一底层对象。
    /// 克隆也只复制位置值，不复制已打开资源或后端状态。
    type Locator: Clone
        + fmt::Debug
        + Eq
        + Ord
        + Hash
        + Send
        + Sync
        + 'static = FileLocator;

    // 当前 namespace 用于证明跨进程文件协调条件的不透明拥有型授权。
    //
    // # 作用与接口位置
    //
    // 本关联类型位于“定位符已经确定、文件资源尚未打开”的资源获取缝。
    // 后续建立授权的方法拥有地返回一个值，协调式打开和命名空间变更通过
    // 共享引用使用它；打开成功的 [`Self::File`] 在内部持有必要的私有协调
    // 核心，因而 [`FileIo`] 的读取、追加、刷新和映射方法不重复暴露本类型。
    //
    // 默认 [`CrossProcessFileAuthority`] 服务于内置本地 adapter。完全不
    // 支持跨进程协调的 adapter 可以保留默认类型并让相关方法返回
    // [`pi_result::ErrorKind::Unsupported`]；采用其它本地或远端协调协议的
    // adapter 可以覆盖为自己的不透明令牌。
    //
    // # 线程、所有权与生命周期
    //
    // `Send` 允许建立 Future 拥有地返回令牌并让调用方在线程间移动它；
    // `Sync` 允许多个线程共享借用同一令牌，分别独立打开资源。它们只表示
    // Rust 内存访问安全，不允许 adapter 绕过同文件追加串行、映射范围租约
    // 或其它协调矩阵。
    //
    // `'static` 要求令牌拥有后端实例、稳定身份值、目标实例代次、受管定位
    // 信息、协调根目录和协议状态，不借用 namespace 调用栈中的临时定位符
    // 或句柄。它不授权永久持有目标文件原生句柄；同样要求 `'static` 的
    // [`Self::File`] 则拥有自己独立打开的必要资源。
    //
    // `Debug + Display` 用于脱敏诊断，不授予序列化或反向解析语义。关联类型
    // 不要求 `Clone`、`Copy`、`Default`、判等、排序、哈希、`Unpin` 或任何
    // 引用转换。公开调用方通过共享引用复用授权；adapter 可以在内部使用
    // 私有引用计数，但不能要求泛型调用方克隆令牌。
    //
    // # 错配与安全边界
    //
    // 类型相同不证明两个授权可以互换。实现必须把 namespace/backend 实例、
    // 目标稳定文件身份、目标实例代次、全局协调根目录的稳定身份和协议版本
    // 绑定到令牌。将另一文件、已经协调删除的旧目标实例或另一后端实例的
    // 令牌用于当前定位符时，必须在创建资源、取得租约或修改目标文件前返回
    // 明确错误。
    //
    // 本关联类型本身不建立安全条件。产生成功值的公共入口必须单独声明
    // `unsafe` 合同，要求所有相关进程和旁路访问遵守相同协议；否则不能用
    // 一个仅靠合作式 sidecar 锁产生的令牌支撑后续安全映射。
    /// 证明调用方已满足跨进程协作前提的不透明授权类型。
    ///
    /// 授权只适用于建立它时绑定的 namespace、目标对象实例和协调配置，不得
    /// 与其它文件或已经被替换、删除后重建的对象互换。它可在线程间移动和
    /// 共享，但不要求可克隆。无法提供该能力的实现应让相关方法返回
    /// [`pi_result::ErrorKind::Unsupported`]。
    type CrossProcessAuthority: fmt::Debug
        + fmt::Display
        + Send
        + Sync
        + 'static = CrossProcessFileAuthority;

    // 由当前 namespace 独立打开并绑定到具体文件或远端对象的活动资源。
    //
    // [`FileIo`] 已经要求 `Send + Sync`，因此本关联类型不重复列出相同约束。
    // `'static` 保证打开资源拥有句柄、客户端和必要配置，不借用 `open` 调用
    // 栈中的临时值。每次独立打开必须产生独立逻辑资源；内置资源不实现
    // `Clone`，本地追加资源也不得通过克隆原生句柄产生。
    //
    // Rust 不能在关联类型 bound 中表达“不得实现 `Clone`”。第三方 adapter
    // 必须把不可克隆作为本 trait 的语义合同遵守；追加和关闭方法还会
    // 使用独占或消费型接收者，防止通过共享引用直接并发驱动同一资源。
    /// 由当前 namespace 独立打开的活动文件资源。
    ///
    /// 每次成功打开都产生独立逻辑资源。公开资源不得依赖调用栈中的临时值，
    /// 也不应通过 `Clone` 产生共享同一写入通道的第二个公开句柄。
    type File: FileIo + 'static;

    // `read_dir` 成功建立后返回的浅层目录项目流。
    //
    // 每个成功项目拥有自己的 [`DirectoryEntry`]；流不借用后端临时目录项。
    // `Send` 允许唯一流值在线程间迁移，缺少 `Sync` 则明确不承诺并发轮询。
    // 不要求 `Unpin`，调用方必须遵守标准 [`Stream`] 的固定规则。
    /// [`Self::read_dir`] 成功后返回的浅层目录项目流。
    ///
    /// 创建期错误由 `read_dir` 的 Future 返回，开始迭代后发现的错误作为流项目
    /// 返回。流允许跨线程移动，但只允许一个消费者按标准 [`Stream`] 规则轮询。
    /// 产生 [`crate::EntryName::Remote`] 时，还必须满足该类型记录的最终依赖图
    /// 跨线程安全前置条件。
    type DirectoryStream<'a>: Stream<
            Item = pi_result::Result<DirectoryEntry<Self::Locator>>,
        > + Send
        + 'a = BoxDirectoryStream<'a, Self::Locator>
    where
        Self: 'a;

    // `walk` 成功建立后返回的递归后代项目流。
    //
    // 每个成功项目拥有 [`WalkEntry`]；遍历根自身不进入流，直接子项深度
    // 从一开始。流中错误表示开始迭代后才发现的失败，创建期错误由
    // [`Self::walk`] 的 Future 返回。局部错误在状态仍可靠时允许继续遍历，
    // 根级或遍历状态已经无法安全继续的错误会终止该流。
    //
    // `Send` 允许唯一流值在线程间迁移，缺少 `Sync` 则禁止并发轮询同一
    // 游标。不要求 `Unpin` 或 `FusedStream`，调用方必须按标准 [`Stream`]
    // 规则固定和消费该活动资源。
    /// [`Self::walk`] 成功后返回的递归遍历流。
    ///
    /// 每个成功项目拥有自身数据。创建期错误由 `walk` 的 Future 返回，遍历期
    /// 错误作为流项目返回；致使遍历状态无法继续的错误会结束该流。
    /// 产生 [`crate::EntryName::Remote`] 时，还必须满足该类型记录的最终依赖图
    /// 跨线程安全前置条件。
    type WalkStream<'a>: Stream<
            Item = pi_result::Result<WalkEntry<Self::Locator>>,
        > + Send
        + 'a = BoxWalkStream<'a, Self::Locator>
    where
        Self: 'a;

    // 查询定位符最终指向对象的可移植元信息快照，并跟随最终符号链接。
    //
    // 本方法是普通定位符查询和 [`DirectoryEntry`] 延迟加载完整元信息的共同
    // 入口。目录枚举结果只保存轻量名称、定位符和可选种类提示，不私藏
    // namespace、后端加载器或异步闭包；需要完整状态时，调用方把目录项的
    // locator 传回本方法。
    //
    // # 参数与返回值
    //
    // `locator` 只在 Future 生命周期内借用，不按值消费，也不要求调用方为
    // 一次查询复制位置。成功返回拥有型 [`FileMetadata<Self::Locator>`]；
    // 它不借用 namespace、locator、底层目录项、文件句柄或响应 buffer，因而
    // 可以在 Future 完成后独立移动和保存。
    //
    // 元信息结构本身不重复保存查询 locator。只有后端提供了可用于条件请求
    // 或版本比较的可靠令牌时，`version` 才包含绑定本次资源位置的
    // [`crate::ResourceVersion`]；adapter 可以为此克隆 `Self::Locator`。
    // 没有可靠版本语义时必须返回 `None`，不能用修改时间、文件长度或随机值
    // 伪造版本。
    //
    // 不存在不是空结果：定位符在查询时无法解析到对象必须返回
    // [`pi_result::Error`]，不能返回 `Option::None` 或虚构一个
    // [`crate::FileType::Unknown`] 元信息值。目录、链接目标、特殊文件或远端
    // 未知长度可以合法地令 `byte_len` 为 `None`；这与对象不存在不同。
    //
    // # 符号链接语义
    //
    // 对具有符号链接语义的本地 adapter，本方法跟随路径最终分量的符号链接，
    // 返回目标对象的类型、长度、权限、时间和可选版本，而不是链接本身。
    // 路径中间分量仍按平台正常路径解析规则处理。悬空链接、解析循环、层数
    // 超限或目标不可访问必须返回相应错误，不能退回链接自身元信息。
    //
    // Windows 重解析点或其它平台链接对象只有在 adapter 能明确映射到本
    // 合同时才采用同样语义；不能可靠分类时应按后端能力返回保守结果或明确
    // 不支持。没有符号链接概念的远端对象后端直接查询 locator 所指对象，
    // 不需要模拟一次不存在的链接跳转。
    //
    // 需要观察最终符号链接本身的调用方必须使用后续单独声明的不跟随查询，
    // 不能从本结果反推链接类型、链接文本或链接自己的时间和权限。
    //
    // # 快照、竞态与一致性
    //
    // 成功结果只是 adapter 在本次调用期间观察到的一次快照，不是锁、事务、
    // 稳定文件身份、打开能力或未来读取保证。查询完成后，对象可能立即被
    // 修改、追加、截断、删除、改名或替换；后续打开同一 locator 也可能取得
    // 另一个对象。调用方不得用“先 metadata、再操作”的两步流程替代需要
    // 稳定文件身份或原子条件请求的接口。
    //
    // adapter 默认必须执行真实查询，不能用没有公开时效、失效和一致性合同
    // 的缓存冒充当前结果。远端后端若自身只提供最终一致或带版本的响应，
    // adapter 必须如实保留其语义；统一返回类型不会把后端结果提升为强一致。
    // 内部为了单次请求去重或协议解析使用短期缓存是实现细节，但不能让调用方
    // 观察到比后端合同更陈旧且未声明的数据。
    //
    // [`DirectoryEntry`] 与本查询之间存在正常的检查后使用竞态：目录项列出
    // 后可能已消失或被替换，本方法必须按查询当时的事实成功或失败，不能让
    // 目录项中可选的类型提示覆盖新查询结果。
    //
    // # 并发、映射与跨进程协调
    //
    // 方法使用 `&self`，同一 namespace 上的多个元信息查询可以并发执行。
    // 它不读取文件内容、不推进游标、不改变映射范围，也不修改 namespace，
    // 因而可以与活动 MMAP、严格追加和其它普通只读元信息查询并存。返回值
    // 只反映查询实际观察到的某一时刻；并发变化可能令不同查询结果不同。
    //
    // 本方法不自动取得 [`crate::CrossProcessFileAuthority`] 的操作租约，也
    // 不因为某个 locator 已加入协调域就承诺线性化到该协议的内容操作。
    // 需要与删除、替换、截断或映射建立强顺序的调用方必须使用相应受管资源
    // 或后续专门的条件操作，不能依赖一次路径元信息快照。
    //
    // # 本地与远端 adapter
    //
    // 标准本地 adapter 使用与 `async_fs::metadata` 等价的跟随查询，并把
    // 平台元信息投影到可移植 [`FileMetadata`] 字段。平台专有 ACL、inode、
    // 所有者、安全描述符或其它扩展不能塞入含义不同的可移植字段；当前 API
    // 未提供相应扩展元信息返回面。
    //
    // 远端 adapter 只能填写后端真实提供且语义足够明确的字段。ETag、generation
    // 或版本 ID 只有能够作为不透明版本令牌使用时才进入 `ResourceVersion`；
    // 对象大小、时间和权限缺失时使用各字段已经定义的未知表示，不能伪造
    // 本地文件属性。后端完全不支持元信息查询时返回明确“不支持”错误。
    //
    // # 错误、取消与 panic
    //
    // 不存在、权限不足、无效或越界定位符、符号链接循环、后端不支持、远端
    // 协议错误、超时、资源耗尽和底层 I/O 失败均通过 [`pi_result::Error`]
    // 返回。实现不得把这些错误折叠为一个 `false` 或 `Unknown`，也不得因
    // 可报告条件 panic。
    //
    // 从未轮询的 Future 不得发起查询。Future 被丢弃后不得修改目标文件或
    // namespace；已经提交的本地阻塞查询或远端请求可以由 adapter 的拥有型
    // 完成者继续收尾，但结果不能再写入已失效的调用方借用。取消仍可能产生
    // 请求、日志、指标或内部临时缓存等非文件内容副作用。
    //
    // # 幂等性、副作用与成本
    //
    // 重复调用不会由本接口主动修改目标，因此调用动作可以安全重复；并发
    // 外部变化会使结果或错误不同，所以它不是结果幂等查询。本方法可能执行
    // 系统调用、远端请求、名称解析、临时分配、日志和指标，因此不是纯函数。
    //
    // 本地成本通常至少包含与 locator 路径长度相关的解析和一次元信息系统
    // 调用；远端通常至少需要一次请求。网络挂载、离线设备、链接解析和远端
    // 服务都可能造成长尾延迟。接口不承诺 O(1) 延迟、零分配、零系统调用或
    // 无阻塞；本地可能阻塞的工作必须由 adapter 的阻塞执行设施承载，不能
    // 长期占用调用方执行器的 poll 线程。
    //
    // Future 为 `Send + 'a`，可以在对 namespace 与 locator 的共享借用期内
    // 跨工作线程迁移，不绑定 Tokio、async-std、Monoio 或其它具体运行时，
    // 也不要求这些借用为 `'static`。
    /// 查询最终定位对象的可移植元信息，并跟随最终符号链接。
    ///
    /// 成功值是拥有型快照，不保证返回后对象仍存在或保持不变。目标不存在、
    /// 链接悬空、权限不足及其它查询失败均返回错误；未知字段必须保持未知，
    /// 不能伪造。该方法不修改文件内容或命名空间，也不为后续操作预留对象。
    fn metadata<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<
        Output = pi_result::Result<FileMetadata<Self::Locator>>,
    > + Send
           + 'a;

    // 查询定位符最终路径分量自身的可移植元信息快照，不跟随最终符号链接。
    //
    // 本方法对应 [`Self::metadata`] 的“不跟随最终分量”版本。它主要用于区分
    // 符号链接对象与其目标、检查悬空链接，以及让 [`DirectoryEntry`] 的
    // 可选种类提示通过一次真实查询得到校准。返回值仍是普通拥有型
    // [`FileMetadata<Self::Locator>`]，不增加链接专用结果类型或隐藏加载器。
    //
    // # 参数、结果与最终分量
    //
    // `locator` 只在 Future 生命周期内借用，不被消费。成功结果拥有全部
    // 可移植快照数据；只有后端提供可靠版本令牌时，结果中的
    // [`crate::ResourceVersion`] 才会拥有一个与本次资源绑定的 locator。
    //
    // 当最终路径分量是可可靠识别的符号链接时，本方法必须返回链接对象自身
    // 的元信息，并令 `file_type` 为 [`crate::FileType::SymbolicLink`]。它不
    // 解析或访问链接目标，所以悬空链接也可以成功。链接自身的 `byte_len`
    // 统一为 `None`：Unix 链接文本长度、Windows 重解析数据长度及远端后端
    // 自有表示并不具有足够一致的“文件内容长度”含义，不能放入同一字段。
    //
    // 最终分量不是符号链接时，返回该对象自身的元信息。它可能与同一时刻
    // [`Self::metadata`] 的结果相同，但两个独立调用之间存在正常竞态，不能
    // 以值相等作为接口保证。
    //
    // 对象不存在必须返回 [`pi_result::Error`]，不能用 `Option::None`、
    // `FileType::Unknown` 或空元信息表示。唯一特别之处是悬空的最终符号链接
    // 本身仍然存在，因此本方法成功，而跟随查询通常返回目标不存在。
    //
    // # 中间分量、Windows 重解析点与远端后端
    //
    // 只有最终路径分量不被跟随；路径中间分量仍按平台正常路径解析规则
    // 处理。中间符号链接悬空、形成循环、超过平台解析限制或通向不可访问
    // 位置时必须返回相应错误。
    //
    // Windows 重解析点不全部等价于符号链接。adapter 只有在能够可靠确认
    // 对象属于本接口的符号链接语义时才能返回 `SymbolicLink`；其它重解析
    // 类型应使用可移植模型中最准确的保守种类，或在无法安全查询时返回
    // “不支持”，不得把所有重解析点一律伪装成链接。
    //
    // 没有符号链接概念的远端 backend 直接查询 locator 指向的对象，本方法
    // 可以与 [`Self::metadata`] 具有相同后端行为。后端如果确实存在链接或
    // 别名语义，却无法执行最终分量不跟随查询，则必须明确返回“不支持”，
    // 不能静默退化为跟随查询并把目标元信息冒充链接自身元信息。
    //
    // 本方法不返回链接保存的目标文本，也不执行规范化或绝对路径解析。
    // `read_link`、`canonicalize` 是否进入核心接口需要以后单独冻结，不能从
    // 当前元信息结果反向推导。
    //
    // # 快照、版本与检查后使用竞态
    //
    // 成功结果是查询期间的一次瞬时观察，不是稳定文件身份、打开句柄、锁、
    // 事务或后续操作保证。链接或非链接对象可能在返回后立即被替换、改名、
    // 删除或修改；调用方不能先调用本方法检查种类，再假定后续路径操作仍然
    // 作用于同一个对象。
    //
    // 可靠版本令牌必须描述本次实际观察的最终对象本身。查询到符号链接时，
    // 不能把目标对象的 ETag、generation、内容摘要或时间戳错误绑定给链接。
    // backend 不能证明链接自身版本时应返回 `None`。
    //
    // [`DirectoryEntry`] 中的种类只是枚举时提示；本方法必须执行真实查询并
    // 以当前结果为准。默认不得使用没有公开时效和失效合同的缓存。远端后端
    // 固有的最终一致性或版本化响应必须如实保留，不能由统一类型提升为强
    // 一致结果。
    //
    // # 并发、映射与副作用
    //
    // 方法使用 `&self`，允许同一 namespace 上的多个查询并发执行。它不读取
    // 普通文件内容、不推进游标、不修改链接或目标，也不改变映射范围，因此
    // 可以与活动 MMAP、严格追加和其它元信息查询并存。并发 namespace 变更
    // 可以让查询观察到成功、旧对象、新对象或不存在中的任一合法时刻。
    //
    // 本方法不取得 [`crate::CrossProcessFileAuthority`] 的内容操作租约，
    // 也不为后续删除、替换、映射或打开建立线性化点。需要稳定身份保证的
    // 操作必须使用专门的受管资源流程。
    //
    // 本接口不修改目标 namespace，但可能执行路径解析、本地元信息系统调用、
    // 远端请求、临时分配、内部短期缓存、日志或指标，因此不是纯函数。重复
    // 调用动作安全，但外部状态变化会导致结果或错误不同，不是结果幂等查询。
    //
    // # 错误、取消、运行时与成本
    //
    // 不存在、权限不足、无效定位符、中间链接错误、后端不支持、远端协议
    // 错误、超时、资源耗尽和底层 I/O 失败都通过 [`pi_result::Error`] 返回，
    // 不得折叠成布尔值或 `Unknown`。所有可报告条件不得 panic。
    //
    // 从未轮询的 Future 不得发起查询。Future 被丢弃后不得修改目标；已经
    // 提交的阻塞查询或远端请求可以由 adapter 的拥有型完成者继续安全收尾，
    // 但不得在 Future 生命周期结束后访问调用方借用。取消仍可能留下日志、
    // 指标或合法的内部短期缓存。
    //
    // Future 为 `Send + 'a`，可以在 namespace 与 locator 的共享借用期内跨
    // 工作线程迁移，不绑定具体异步运行时，也不要求借用为 `'static`。本地
    // 可能阻塞的查询必须由 adapter 的阻塞执行设施承载。成本通常至少包含
    // 与路径长度相关的解析及一次系统调用或远端请求；接口不承诺固定延迟、
    // 零分配、零系统调用或无阻塞。
    /// 查询最终路径分量自身的可移植元信息，不跟随最终符号链接。
    ///
    /// 本方法用于区分链接对象与其目标以及检查悬空链接。成功值是拥有型
    /// 快照；不存在或其它查询失败返回错误。中间路径分量仍按所在系统或
    /// 后端的正常规则解析。
    fn symlink_metadata<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<
        Output = pi_result::Result<FileMetadata<Self::Locator>>,
    > + Send
           + 'a;

    // 查询定位符跟随最终符号链接后是否指向一个当前可观察的对象。
    //
    // 本方法用于只需要存在性而不需要完整 [`FileMetadata`] 的调用路径。
    // 名称中的 `try` 强调：只有后端权威地确认目标不存在时才返回 `false`；
    // 权限、解析、网络和后端错误必须保留在 [`pi_result::Error`] 中，不能像
    // 某些便利型 `exists` 接口那样吞掉错误。
    //
    // # 参数、返回值与符号链接
    //
    // `locator` 只在 Future 生命周期内借用，不被消费。成功结果具有严格的
    // 三分语义：
    //
    // - `Ok(true)`：本次查询确实观察到 locator 跟随最终符号链接后存在目标；
    // - `Ok(false)`：本次查询的权威后端明确报告该目标不存在；
    // - `Err(error)`：无法可靠回答存在或不存在，原因保留在错误中。
    //
    // 本方法跟随最终符号链接，与 [`Self::metadata`] 的解析方向一致。最终
    // 分量是悬空符号链接时返回 `Ok(false)`，因为被查询的目标不存在；这不
    // 表示链接对象本身不存在。需要区分悬空链接和完全不存在时，调用方应
    // 使用 [`Self::symlink_metadata`]，而不是要求第二个浅层
    // `try_symlink_exists` 接口。
    //
    // 中间路径分量仍按平台正常规则解析。中间符号链接悬空、循环、越过后端
    // 允许范围或不可访问时返回错误，不能仅因最终结果不可达就一律返回
    // `false`。没有符号链接概念的远端后端直接判断 locator 对象是否存在。
    //
    // # “权威不存在”的边界
    //
    // 本地 adapter 只有在平台返回明确的对象或路径未找到结果时才能返回
    // `Ok(false)`。权限不足、路径分量不是目录、文件名无效、链接循环、资源
    // 耗尽和其它 I/O 错误均返回 `Err`。adapter 必须根据具体平台错误语义
    // 分类，不能只要元信息查询失败就判定不存在。
    //
    // 远端 adapter 只有在已认证、已路由到正确 backend 和命名空间作用域后，
    // 收到该后端合同定义的权威缺失响应时才能返回 `false`。超时、连接失败、
    // 服务不可用、凭据过期、限流、响应歧义、最终一致性窗口无法判定或后端
    // 根本不支持可靠存在性查询时必须返回 `Err`。
    //
    // 如果 backend 公开合同本身只能提供最终一致的“不存在”，adapter 可以
    // 返回该观察结果，但必须在 backend 级文档中声明一致性边界；统一 bool
    // 不把它提升为全局强一致事实。
    //
    // # 实现深度与元信息关系
    //
    // adapter 可以使用更便宜的本地存在性原语、远端 HEAD/条件请求，也可以
    // 内部复用 [`Self::metadata`] 的查询路径。无论采用哪种实现，公开错误
    // 分类和跟随链接语义都必须一致。不能为了返回 bool 而构造并丢弃虚假的
    // [`FileMetadata`]，也不能在完整元信息不可用时仅因该原因拒绝一个后端
    // 能够可靠回答的存在性查询。
    //
    // 默认不得使用没有公开时效、失效和一致性合同的缓存。单次请求去重或
    // backend 自身明确提供的缓存语义可以使用，但返回值始终只是本次查询
    // 所能证明的快照。
    //
    // # 快照、竞态与并发
    //
    // `true` 不是锁、预留、稳定文件身份或后续打开保证；返回后对象可以立即
    // 被删除、改名或替换。`false` 也不阻止另一个线程或进程随后创建对象。
    // 调用方不得用“先判断不存在、再创建”实现排他创建，也不得用“先判断
    // 存在、再修改”代替原子条件操作。
    //
    // 方法使用 `&self`，允许并发存在性查询。它不读取普通文件内容、不推进
    // 游标、不修改 namespace 或映射范围，可以与活动 MMAP、严格追加和其它
    // 元信息查询并存。并发变化可以使相邻两次调用返回不同结果。
    //
    // 本方法不取得 [`crate::CrossProcessFileAuthority`] 的内容操作租约，也
    // 不与协调域中的删除、替换或创建建立强顺序。需要稳定身份和操作矩阵
    // 保证时必须使用相应受管资源入口。
    //
    // # 错误、取消、幂等性与副作用
    //
    // 权限不足、无效 locator、非目录中间分量、链接循环、后端不支持、超时、
    // 认证失败、限流、资源耗尽和底层 I/O 错误通过 [`pi_result::Error`] 返回。
    // 满足接口前置条件的可报告情况不得 panic。
    //
    // 从未轮询的 Future 不得发起查询。Future 被丢弃后不得修改目标文件或
    // namespace；已经提交的阻塞系统调用或远端请求可以由 adapter 的拥有型
    // 完成者继续安全收尾，但不得继续访问调用方借用。取消仍可能产生请求、
    // 日志、指标或内部短期缓存等非文件副作用。
    //
    // 重复调用动作本身安全且不会由接口主动修改目标，但外部状态和 backend
    // 一致性窗口会改变结果，因此不是结果幂等。查询可能执行系统调用、远端
    // 请求、路径解析、临时分配、日志或指标，所以不是纯函数。
    //
    // # 异步运行时与成本
    //
    // Future 为 `Send + 'a`，可以在 namespace 与 locator 的共享借用期内跨
    // 工作线程迁移，不绑定具体异步运行时，也不要求借用为 `'static`。本地
    // 可能阻塞的查询必须由 adapter 的阻塞执行设施承载，不能长期占用宿主
    // 执行器的 poll 线程。
    //
    // 本地通常至少需要一次路径解析和系统调用，远端通常至少需要一次请求；
    // 网络挂载、离线设备和远端服务可能造成长尾延迟。接口不承诺固定延迟、
    // 零分配、零系统调用或无阻塞。
    /// 查询最终定位对象当前是否存在，并跟随最终符号链接。
    ///
    /// 只有能够确认“不存在”时才返回 `Ok(false)`；权限、解析、网络或后端
    /// 故障必须返回错误。返回值只是瞬时观察，不能代替排他创建、条件修改或
    /// 稳定身份核验。
    fn try_exists<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::Result<bool>> + Send + 'a;

    // 查询定位符所在存储作用域当前报告的候选可用空间快照。
    //
    // locator 指向文件或目录等具体对象，容量却属于包含它的更大存储作用域，
    // 例如 Windows 卷或共享、Linux 已挂载文件系统、WebDAV 配额根，或者专有
    // 远端后端明确声明的账户/租户配额。本方法把平台解析和后端路由隐藏在
    // namespace adapter 内，只返回统一的 [`AvailableSpace`]。
    //
    // # 参数、现存对象与符号链接
    //
    // `locator` 只在 Future 生命周期内借用，不被消费。第一版要求它在查询
    // 时解析到一个真实存在且当前身份可访问的对象；本地普通文件和目录都可
    // 作为查询锚点。对象不存在、路径悬空或远端对象缺失必须返回错误，不能
    // 自动逐级寻找最近存在的父目录并猜测未来创建位置所在作用域。
    //
    // 这个“必须现存”的限制使 Windows 和 Linux 保持一致，也防止重命名、
    // 挂载变化或远端路由规则让一个不存在的文本地址产生误导结果。以后若
    // 确实需要为计划创建位置估算容量，必须单独设计显式模式和父级选择合同。
    //
    // 最终分量是符号链接时，本方法跟随目标，返回目标对象所在存储作用域的
    // 可用空间。悬空链接返回未找到。路径中间分量按平台正常规则解析；链接
    // 循环、权限不足或解析错误必须保留为错误。没有符号链接概念的远端后端
    // 直接使用 locator 确定容量作用域。
    //
    // # 本地跨平台数值
    //
    // Windows adapter 必须查询最终对象所在的卷、卷挂载文件夹或明确支持的
    // 文件共享，并使用实际查询执行身份看到的 caller-available 字节数。用户
    // 配额可能使该值小于卷总空闲量；接口不把它描述为无条件物理磁盘余量。
    // 长路径、UNC、重解析点和卷挂载路径必须由 adapter 按其公开支持矩阵验证，
    // 不能用固定短缓冲截断后继续查询。
    //
    // Linux adapter 必须查询最终对象所在的已挂载文件系统，并使用受检的
    // `f_frsize * f_bavail` 字节换算；`tmpfs` 属于正常已挂载文件系统。该值
    // 表达文件系统为非特权访问者报告的可用块，不能宣称所有文件系统都完整
    // 纳入用户、组和项目配额。乘法超出 `u64` 必须返回溢出错误，不能饱和、
    // 截断或回绕。
    //
    // 相同路径文本在不同 Windows 身份、Linux 挂载命名空间或容器上下文中
    // 可以得到不同结果。本合同采用 adapter 实际执行查询时的后端身份和
    // namespace 上下文，不承诺自动传播调用线程特有的 Windows impersonation
    // token、Linux mount namespace 或当前目录。依赖这些线程局部上下文的
    // 应用必须使用能明确固定该执行环境的专用 adapter。
    //
    // # 远端能力边界
    //
    // 远端 adapter 只有在协议或供应商提供语义明确、可认证并与当前 namespace
    // 配置绑定的容量或配额接口时才能返回成功。例如启用相应属性的 WebDAV
    // 或专有存储配额接口可以支持；adapter 必须用 receiver 中的 endpoint、
    // 凭据、租户和配置确定作用域，不能只根据 URL scheme 猜测。
    //
    // 标准 S3、普通 HTTP、没有有限容量合同的内存后端，以及 Fusio 通用文件
    // 系统接口本身都不能提供统一剩余空间，必须返回能力不支持。单对象大小
    // 上限、账户费用、对象数量上限或 `u64::MAX` 都不能冒充剩余字节。
    //
    // 只提供隐私保护或实现决定估计值的后端也不进入第一版成功域，因为
    // [`AvailableSpace`] 刻意不携带估计质量和作用域字段；这类 adapter 必须
    // 返回不支持，直到以后由独立结果模型明确承载估计语义。
    //
    // 本方法接收 `Self::Locator`，不另造只供容量查询使用的 `PathOrUrl`。
    // 单一 backend namespace 可以使用自己的原生 locator；需要和类型路由的
    // 组合 namespace 可以使用 [`FileLocator`]，仍由 receiver 的静态类型和
    // 配置选择真实 adapter。
    //
    // # 成功快照与不保证事项
    //
    // `Ok(AvailableSpace)` 表示后端已经为实际查询上下文报告一个可无损表示的
    // 当前候选可用字节数。零和 `u64::MAX` 都是合法数值，绝不能兼作错误哨兵。
    //
    // 结果可能立即过期，不预留空间，不证明 locator 当前可写，也不保证随后
    // 可以写入相同数量。并发写入、只读挂载、inode 耗尽、压缩/稀疏策略、
    // 文件大小上限、额外配额、远端策略和设备错误仍可能让写入失败。调用方
    // 不得以本结果替代真实写入错误处理或容量预留协议。
    //
    // 默认不得使用没有公开时效、失效和一致性合同的缓存。远端后端固有的
    // 一致性窗口必须如实保留；统一快照类型不把它提升为强一致结果。
    //
    // # 并发、MMAP 与副作用
    //
    // 方法使用 `&self`，允许同一 namespace 上的容量查询并发执行。它不读取
    // 普通文件内容、不推进游标、不修改目标或范围，可以与活动 MMAP、严格
    // 追加、元信息查询和其它容量查询并存。并发变化可以使相邻查询返回不同
    // 数值。
    //
    // 本方法不取得 [`crate::CrossProcessFileAuthority`] 的内容操作租约，也
    // 不为返回的容量建立预留。需要与写入、删除、替换或挂载变更建立强顺序
    // 的应用必须使用底层专用协议，不能依赖本快照。
    //
    // 查询不修改目标文件或 namespace，但不是纯函数：Linux 路径解析可能
    // 触发自动挂载，Windows 共享或其它网络挂载可能产生网络访问，远端查询
    // 会发出请求；实现还可能使用阻塞 worker、临时分配、日志和指标。
    //
    // # 错误与能力分类
    //
    // 后端从根本上没有容量合同、后端原则上支持但当前配置或身份无法取得、
    // locator 无效、对象不存在、权限不足、算术溢出、网络或设备错误、超时
    // 和资源耗尽均通过 [`pi_result::Error`] 返回。精细原因由 adapter 的
    // `thiserror` 错误保存并按项目规则转换；不能把它们折叠为数值零或
    // 一个无法区分是否应重试的通用成功值。
    //
    // 满足接口前置条件的可报告失败不得 panic。平台原始错误或远端 source
    // 应保留用于诊断，但公开合同不泄漏 `windows-sys`、`rustix`、Fusio 或
    // 云 SDK 的具体错误类型。
    //
    // # 取消、阻塞隔离与异步运行时
    //
    // 本地空间查询通常是同步系统调用。adapter 必须把可能阻塞的卷、挂载点
    // 或文件系统查询放入内部阻塞设施，不能直接长期占用调用方执行器的 poll
    // 线程。网络挂载、失效设备、不可达共享或自动挂载可能长时间等待，adapter
    // 应使用有界准入和资源隔离，避免少数查询耗尽普通文件 I/O 的全部 worker。
    //
    // 从未轮询的 Future 不得开始查询。Future 被丢弃只表示调用方停止等待；
    // 已经进入同步系统调用的 worker 通常无法被 Rust Future 抢占，必须由
    // adapter 的拥有型完成者继续安全收尾并丢弃结果。调用方在外层设置超时
    // 也不能被描述为底层查询已经终止或 worker 已经释放。
    //
    // 本方法不接收具体 runtime、线程池或逐调用超时参数。阻塞池、并发上限、
    // 身份上下文和故障隔离属于 adapter 配置；把这些内部接缝暴露给每个调用
    // 会扩大接口且仍不能统一取消平台系统调用。
    //
    // Future 为 `Send + 'a`，可以在 namespace 与 locator 的共享借用期内跨
    // 工作线程迁移，不绑定 Tokio、async-std、Monoio 或其它具体运行时，也
    // 不要求借用为 `'static`。
    //
    // # 幂等性与成本
    //
    // 调用动作不主动修改目标，可以安全重复；每次都可能观察新的容量、执行
    // 新系统调用或请求并独立失败，因此不是结果幂等或无副作用操作。本地
    // 通常至少需要路径解析和一次容量系统调用，远端通常至少一次请求；接口
    // 不承诺固定延迟、零分配、零系统调用或无锁。
    /// 查询定位符所在存储作用域当前报告的候选可用字节数。
    ///
    /// 本地位置通常对应其卷、分区或挂载点；远端位置只有在后端提供明确容量
    /// 合同时才受支持。成功返回 [`AvailableSpace`] 快照，不表示调用方一定能
    /// 分配相同大小，也不为后续写入保留空间。目标、存储作用域或该能力无法
    /// 确定时返回错误，不能以零表示“不支持”。
    fn available_space<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::Result<AvailableSpace>> + Send + 'a;

    // 建立一个惰性的浅层目录项目流。
    //
    // 本方法是 namespace 的直接子项枚举入口。它异步打开 `locator` 所指
    // 目录或建立远端首个分页游标，随后把每个直接子项作为拥有型
    // [`DirectoryEntry`] 逐项交给调用方。它不递归、不包含根目录自身，也不
    // 为排序或批量元信息一次性加载整个目录。
    //
    // # 参数、所有权与返回层次
    //
    // `locator` 按所有权传入，使返回流可以直接拥有根位置，而不必为了脱离
    // 调用栈强制克隆一个可能较大的路径或 URL。方法完成后不返还 locator；
    // 需要继续使用同一位置的调用方必须在调用前显式克隆。
    //
    // 外层 Future 与项目流有不同的失败阶段：
    //
    // - Future 负责解析根位置、核验目录枚举能力、打开本地目录或建立远端
    //   首个分页游标；这些步骤失败时不产生流；
    // - Future 成功后，逐项读取、目录项解码、后续分页和并发变化导致的错误
    //   通过 [`Self::DirectoryStream`] 的项目错误通道报告。
    //
    // Future 成功不表示目录非空。空目录返回一个正常流，该流在第一次有效
    // 轮询时结束；不能用错误或一个伪造项目表达空目录。
    //
    // `Self::DirectoryStream<'a>` 可以在 `'a` 内借用 namespace 的后端配置，
    // 但每个成功项目拥有名称和完整子项 locator，不借用根 locator、临时
    // backend 响应或目录读取 buffer。流 Drop 后，已经产出的项目仍可独立
    // 保存和移动。
    //
    // Future 成功返回时必须完成明确的所有权交接：本地目录句柄、远端分页
    // 游标、已分配 buffer 和取消状态要移动进返回流。流不得借用已经完成的
    // Future 栈帧、局部 `ReadDir` 引用或临时错误转换器。需要在流 Drop 后
    // 继续收尾的后台任务必须独立拥有其状态，不能保存指向流内存的裸借用。
    //
    // 默认 [`BoxDirectoryStream`] 可以固定并擦除 `async-fs` 转换流、宏生成
    // 流或远端分页状态机的具体类型。装箱后的 `+'a` 只是对捕获引用的有效期
    // 要求，不是生命周期延长手段；实际状态不足 `'a` 时实现必须无法编译，
    // 禁止用 `transmute`、内存泄漏或手写 auto-trait 实现绕过。
    //
    // # 浅层范围与目录项
    //
    // 流只产生根目录的直接子项，不产生根自身，也不递归进入子目录。标准
    // 本地目录枚举不得产生 `.` 或 `..`；普通隐藏文件和平台可见的其它目录项
    // 不能因为名称以点开头或具有隐藏属性而被默认过滤。
    //
    // 每个成功项目包含：
    //
    // - 拥有型 [`crate::EntryName`]；
    // - 当前 namespace 可以继续接受的完整 `Self::Locator`；
    // - 枚举响应已经免费携带时的可选 [`crate::FileType`] 提示。
    //
    // adapter 不得仅为了填充类型提示而隐式追加一次元信息查询；底层枚举
    // 没有可靠提示时必须返回 `None`。提示描述枚举时观察到的目录项自身，
    // 不能跟随子项的最终符号链接后把目标类型冒充为链接类型。需要当前完整
    // 状态时，调用方必须把项目 locator 传给 [`Self::metadata`] 或
    // [`Self::symlink_metadata`]。
    //
    // 项目名称和 locator 必须来自同一个底层枚举结果。实现不能重新扫描目录
    // 后把另一次观察中的名称、类型和位置拼成一个看似原子的项目。
    //
    // # 快照、顺序与并发变化
    //
    // 目录流不是快照、事务或稳定文件身份集合。枚举期间，子项可以被创建、
    // 删除、改名、替换或改变类型；已经返回的 locator 也可能立即失效或指向
    // 另一个对象。调用方不能用一次 `read_dir` 结果替代操作时的身份核验。
    //
    // 本接口不保证字典序、创建顺序、文件系统内部顺序或跨平台一致顺序，也
    // 不在并发变化下保证无重复、无遗漏或恰好一次观察。需要稳定应用视图的
    // 调用方必须建立自己的版本、快照或重新扫描协议；统一流类型不会提升
    // 底层文件系统或远端服务的一致性等级。
    //
    // adapter 不得为了提供确定排序而静默收集整个目录。调用方需要排序时，
    // 应显式消费并排序结果，承担相应的 `O(N)` 内存和 `O(N log N)` 比较成本。
    //
    // # 项目错误与终止
    //
    // 初始化成功后发现的单项目读取错误、目录句柄错误、响应解码错误和远端
    // 后续分页错误必须作为一个 `Err` 项目报告。产生首个项目错误后，流进入
    // 终止状态，不再产生其它成功项目或重复错误。继续枚举一个已经证明不完整
    // 的视图会诱使调用方把部分结果误认为完整结果；需要恢复时必须重新建立
    // 一次新流。
    //
    // 终止语义不要求关联类型实现 [`futures_core::FusedStream`]。调用方仍须
    // 遵守普通 [`Stream`] 规则，在观察到结束后不再假设可以恢复同一游标。
    //
    // locator 无效、根不存在、根不是可枚举目录、权限不足、链接解析失败、
    // 后端没有目录或前缀枚举能力、资源耗尽、远端协议错误和底层 I/O 失败均
    // 通过对应阶段的 [`pi_result::Error`] 返回。可报告条件不得 panic，也不
    // 能把“不支持枚举”伪装成一个正常空目录。
    //
    // # 本地与远端语义
    //
    // 标准本地 adapter 使用平台目录枚举语义，并把目录读取资源独立于普通
    // 文件数据句柄、MMAP 句柄和文件监听资源维护。根 locator 中符号链接和
    // Windows 重解析点的解析服从该 adapter 公开的路径规则；子项类型提示
    // 仍只描述枚举直接观察到的目录项事实。
    //
    // 远端 adapter 只有在 backend 明确提供列表或前缀枚举能力时才能实现本
    // 方法。对象存储的前缀、分隔符、分页一致性和目录占位对象必须按 backend
    // 真实语义映射；不能把任意 URL 文字前缀伪装成完整 POSIX 目录，也不能
    // 因后端不支持列表而返回空流。
    //
    // 第一版不接收排序、过滤、批量元信息、错误继续或递归选项。递归遍历由
    // 独立的 [`Self::WalkStream`] 接口承载；其它策略需要未来通过明确 helper
    // 和独立签名扩展，不能由 adapter 私下改变本方法的结果范围。
    //
    // # 并发、取消与资源生命周期
    //
    // 同一 namespace 可以并发建立多个目录流，每次成功调用都产生独立的
    // 逻辑游标或分页状态。单个流只允许一个消费者按 [`Stream`] 规则顺序
    // 轮询；`Send` 允许流在线程间迁移，不授予 `Sync`、并发轮询、`Clone`、
    // `Unpin` 或可重复消费语义。
    //
    // 本方法只枚举名称和轻量提示，不读取文件内容、不建立 MMAP、不推进文件
    // 游标，也不取得读取、追加、覆盖或截断操作租约。它可以与这些内容操作
    // 并存，但不与并发改名、删除或创建形成事务顺序；不同轮询可能观察到
    // 不同 namespace 状态。
    //
    // 从未轮询的 Future 不得打开目录或发出远端请求。Future 在初始化期间
    // 被丢弃后，已经提交的阻塞打开或网络请求必须由内部拥有型完成者安全
    // 收尾；最终建立但未交付的游标必须关闭，不能泄漏目录句柄或分页会话。
    //
    // 流 Drop 表示取消尚未请求的后续枚举并释放其活动资源。已经提交的同步
    // `readdir`、阻塞 worker 或远端分页请求不一定能被抢占；内部完成者必须
    // 等其停止访问内部状态后再关闭资源和丢弃结果。Drop 不同步等待，也不
    // 触发重新扫描、排序、元信息补查或用户回调。
    //
    // 本地可能阻塞的目录打开和逐项读取必须由 adapter 的有界阻塞设施承载，
    // 不能长期占用调用方执行器的 poll 线程。Future 和流都不绑定具体异步
    // 运行时；返回 Future 为 `Send + 'a`，流的线程属性由已经声明的关联类型
    // 合同给出。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法不主动修改 namespace 或文件内容，但会打开目录句柄、创建远端
    // 游标、分配流状态、使用阻塞设施、发出请求并更新日志或指标，因此不是
    // 纯函数。重复调用可以建立新的独立枚举，但不同调用可能观察不同结果，
    // 也可能分别失败；它不是结果幂等或资源幂等操作。
    //
    // 初始化通常承担 `O(P)` 路径解析或一次远端首请求，`P` 是 locator 的
    // 路径或键长度。随后每个本地项目期望摊销 `O(1)`；远端 adapter 可以为
    // 当前响应页保留 `O(page_size)` 内存。实现不得默认累积全部 `N` 个项目，
    // 也不承诺固定延迟、零分配、零系统调用、零网络请求或无文件系统阻塞。
    /// 建立一个惰性的浅层目录项目流。
    ///
    /// `locator` 按值移入返回流的生命周期。成功只表示流已建立；之后发现的
    /// 项目错误由流返回。流只产生直接子项，不包含根、不递归、不承诺顺序或
    /// 快照一致性。流不会冻结目录；并发创建、删除或改名可以成功，新状态可能
    /// 被观察、遗漏或重复观察。每个成功项目拥有自身名称和定位符，可在流释放
    /// 后保存，但定位符表示的位置仍可能继续变化。
    fn read_dir<'a>(
        &'a self,
        locator: Self::Locator,
    ) -> impl Future<
        Output = pi_result::Result<Self::DirectoryStream<'a>>,
    > + Send
           + 'a;

    // 建立一个惰性的递归后代遍历流。
    //
    // 本方法是 namespace 的递归目录遍历入口。它异步校验并打开 `locator`
    // 所指的遍历根或建立远端遍历游标，随后按 [`WalkOptions`] 规定的逻辑
    // 深度范围，把每个后代作为拥有型 [`WalkEntry`] 逐项交给调用方。遍历根
    // 自身永远不进入流，根的直接子项深度为一。
    //
    // 本接口只统一递归遍历的范围、项目、错误和生命周期语义，不把底层文件
    // 系统提升为事务快照，也不规定深度优先、广度优先或同层排序。需要稳定
    // 应用视图的调用方必须使用后端快照、版本或自己的重扫协议。
    //
    // # 参数顺序、所有权与返回层次
    //
    // 参数顺序固定为“遍历根、遍历选项”。`locator` 按所有权传入，使初始化
    // Future 可以把根位置直接移交给返回流、阻塞任务或取消后的拥有型完成者，
    // 不必为了跨越异步阶段强制克隆一个可能较大的路径或 URL。调用完成后不
    // 返还 locator；需要保留同一位置的调用方必须在调用前显式克隆。
    //
    // `options` 同样按所有权传入。首版只有 [`crate::WalkDepthLimit`]，不接受
    // 排序、过滤、元信息预取、符号链接跟随、并发度或实现专有分页参数。
    // `WalkOptions` 标记为 `non_exhaustive` 只为以后加入确实具有跨后端意义的
    // 选项保留演进空间，adapter 不得通过私有配置改变本方法已经公开的范围。
    //
    // 外层 Future 与返回流承担不同失败阶段：
    //
    // - Future 负责解析根位置、核验递归枚举能力、验证根的存在和目录语义，
    //   并建立首个本地目录状态或远端遍历游标；这些步骤失败时不产生流；
    // - Future 成功后，读取后代、进入子目录、解码项目以及取得后续分页时
    //   发现的错误通过 [`Self::WalkStream`] 的项目错误通道报告。
    //
    // 成功建立流不表示存在任何后代。空目录以及明确使用
    // [`crate::WalkDepthLimit::Limited`] 且 `max_depth` 为零的请求都会返回
    // 正常空流；后者仍必须完成根定位符的语法、存在性、目录语义和能力校验，
    // 不能仅根据零上限跳过初始化并把无效根伪装成成功。
    //
    // # Future 与 Stream 的生命周期交接
    //
    // 返回 Future 只借用 namespace 的 `&'a self`，并拥有 `locator`、
    // `options` 及初始化状态。成功返回时，本地目录句柄、待访问目录栈、当前
    // 目录流、远端分页游标、深度、响应 buffer 和取消状态必须完整移动进
    // `Self::WalkStream<'a>`；流不得引用已经完成的 Future 栈帧、局部变量、
    // 临时 `ReadDir` 引用或只在一次 poll 中有效的后端响应。
    //
    // 流可以在 `'a` 内借用 namespace 中确实存活的后端配置，也可以拥有全部
    // 状态。`'a` 只是允许借用的最长期限，不会延长内部引用的真实生命周期。
    // 一个实际为 `'static` 的拥有型流可以安全收窄到 `'a`；反方向禁止通过
    // `transmute`、泄漏内存、裸指针或手写 auto-trait 实现伪造生命周期。
    //
    // 默认 [`BoxWalkStream`] 使用固定装箱隐藏宏生成流、第三方遍历器或远端
    // 分页状态机的具体类型，因此每次建流至少有一次堆分配，每次 poll 有一次
    // 动态分派。装箱不会为每个项目重复分配适配器，也不能把 `!Send` 状态
    // 变成 `Send`。性能敏感 adapter 可以覆盖关联类型为自己的具体流，但必须
    // 保持完全相同的项目、线程与生命周期合同。
    //
    // 每个成功产生的 [`WalkEntry`] 拥有 [`DirectoryEntry`]、完整子项 locator
    // 和非零深度，不借用遍历根、目录 buffer、分页响应、流或 namespace。
    // 已经产生的项目可以在流或 namespace 被释放后继续保存和移动。
    //
    // # 深度范围与符号链接
    //
    // 遍历根不产生项目。直接子项深度为 `1`，其子项为 `2`，依此类推。
    // [`crate::WalkDepthLimit::Limited`] 的 `max_depth` 是包含式最大深度：位于
    // 上限的项目仍会产生，但实现不得再进入该项目所表示的子目录。
    //
    // [`crate::WalkDepthLimit::Unlimited`] 只表示本库不设置额外逻辑深度上限，
    // 不取消平台路径长度、整数表示、目录句柄、内存、远端分页、配额或其它
    // 资源限制。实现必须在计算下一深度和进入下一层之前检查整数溢出与资源
    // 预算，无法继续时返回结构化错误，不得因深度加一溢出而 panic。
    //
    // 符号链接目录项作为普通后代项目产生，但永远不跟随、不进入其目标。
    // 这同时避免链接循环、越出根目录以及本地与远端别名语义不一致。Windows
    // 重解析点只有在 adapter 能可靠映射为本接口的符号链接语义时才使用同一
    // 规则；其它特殊对象按最准确的可移植类型提示产生或报告不支持。
    // 已经产出的普通目录项也不是后续下降的永久授权：若它在产生后、下降前
    // 被替换成可识别的目录链接，adapter 可以把该子树视为并发遗漏或产生一个
    // 项目错误，但绝不能沿替换后的链接进入其目标。先前的类型提示不能覆盖
    // 下降时观察到的链接事实。
    //
    // # 项目错误、子树恢复与终止
    //
    // 初始化后发现的单项目读取失败、项目解码失败、无法进入某个子目录或
    // 单个远端子前缀失败，必须作为一个 `Err` 项目产生。若 adapter 仍能证明
    // 剩余目录栈、兄弟项目和分页状态可靠，就跳过无法继续的项目或子树并继续
    // 遍历；不得重复产生同一失败，也不得把失败子树伪装成一个正常空目录。
    //
    // 根级状态失效、当前遍历器或分页令牌损坏、目录栈无法恢复、状态一致性
    // 已无法判断以及其它无法安全继续的错误，必须产生一次 `Err` 后终止流。
    // adapter 不能为了看起来“尽量继续”而在未知状态中重复、遗漏或混合不同
    // 根的项目。调用方需要统一“首错即停”时，可以在观察到任意错误后立即
    // Drop 流；首版不为此增加第二种流类型或错误策略选项。
    //
    // 终止语义不要求关联类型实现 [`futures_core::FusedStream`]。调用方仍须
    // 遵守标准 [`Stream`] 合同，在观察到结束后不继续假定同一游标可以恢复。
    // 所有可报告的路径、权限、能力、资源、后端和 I/O 错误都必须进入
    // [`pi_result::Error`]，不能 panic 或静默截断结果。
    //
    // # 顺序、快照与并发变化
    //
    // 本接口不保证深度优先、广度优先、字典序、创建顺序、文件系统内部顺序
    // 或跨 adapter 一致顺序。实现不得为了提供隐藏排序而收集整棵目录树；
    // 调用方需要排序时必须显式收集，并承担 `O(N)` 内存和至少
    // `O(N log N)` 比较成本。
    //
    // 整次遍历不是快照、事务或稳定身份集合。遍历期间项目可以被创建、删除、
    // 改名、替换或改变类型；可能出现底层真实语义允许的遗漏、重复或已经
    // 失效的 locator。已经产生的项目只表达该次读取曾观察到的事实，不能
    // 替代后续内容操作时的稳定身份核验。
    //
    // 本方法只枚举 namespace 项目和轻量类型提示，不读取普通文件内容、不
    // 建立 MMAP、不推进文件内容游标，也不取得读取、追加、覆盖或截断操作
    // 租约。它可以与这些内容操作并存，但不与并发创建、删除或改名形成库级
    // 事务顺序。特定平台或文件系统仍可因活动目录枚举资源拒绝某次删除或改名，
    // 此时相应操作直接返回平台错误，不能把它解释为跨平台互斥保证。不同流或
    // 同一流的不同时刻可以观察到不同 namespace 状态。
    //
    // # 本地与远端 adapter
    //
    // 标准本地 adapter 可以包装成熟的异步目录遍历器，也可以用 `async-fs`
    // 目录流建立私有遍历状态机，但选择的实现必须在进入下一层之前执行本
    // 接口的深度和溢出检查。若第三方遍历器不能可靠阻止越界下降或不能映射
    // 本接口的错误继续语义，就不能仅在输出端过滤越界项目，而必须由 adapter
    // 接管相应状态机。
    //
    // 远端 adapter 只有在 backend 明确提供层级列表、递归前缀遍历或等价
    // 能力时才能实现本方法。对象存储的分隔符、目录占位对象、分页一致性、
    // 速率限制和最终一致性必须按真实语义映射；不能把任意 URL 字符串前缀
    // 冒充完整 POSIX 目录树。后端不支持时必须返回明确“不支持”错误。
    //
    // # 取消、线程与运行时
    //
    // 同一 namespace 可以并发建立多个遍历流，每次成功调用产生独立逻辑
    // 游标和遍历状态。单个流只允许一个消费者按 [`Stream`] 规则顺序 poll；
    // `Send` 允许唯一流值在线程间迁移，不授予 `Sync`、并发 poll、`Clone`、
    // `Unpin`、可重复消费或从旧位置恢复语义。
    //
    // 返回 Future 为 `Send + 'a`，流的线程属性由关联类型合同给出。二者均不
    // 绑定 Tokio、async-std、smol、Monoio 或其它具体运行时。需要
    // `Send + 'static` 顶层任务的调用方应让外层 `async move` 拥有 namespace，
    // 再在任务内部借用它调用本方法；本接口不通过强制克隆 backend 来伪造
    // `'static` 返回流。
    //
    // 从未轮询的 Future 不得打开目录或发出请求。初始化 Future 被丢弃后，
    // 已经提交且无法抢占的阻塞打开或远端请求必须由拥有型完成者安全收尾，
    // 最终建立但未交付的目录句柄、分页会话和登记状态必须被释放。
    //
    // 流 Drop 表示取消尚未发起的后续下降和分页，并释放当前目录栈、句柄、
    // buffer 与游标。已经提交的同步读取、阻塞 worker 或远端请求不一定能被
    // 抢占；内部完成者必须拥有其全部状态，不能在流 Drop 后继续引用流内存。
    // Drop 不同步等待，也不触发重扫、排序、元信息补查或用户回调。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法不主动修改 namespace 或文件内容，但会打开目录、建立远端游标、
    // 分配遍历状态、使用阻塞设施、发出请求并更新日志或指标，因此不是纯
    // 函数。重复调用可以建立新的独立遍历，但可能观察到不同结果并分别失败，
    // 不是结果幂等或资源幂等操作。
    //
    // 访问 `N` 个实际项目通常需要 `O(N)` 总时间；深度优先式本地 adapter
    // 通常保留 `O(D)` 遍历状态，`D` 是当前深度，远端 adapter 还可保留一个
    // 或少量受限响应页。实现不得默认收集全部项目或进行无界预取。每个本地
    // 项目期望摊销 `O(1)` 读取与适配成本，但接口不承诺固定延迟、零分配、
    // 零系统调用、零网络请求或无文件系统阻塞。
    /// 按 [`WalkOptions`] 建立一个惰性的递归后代遍历流。
    ///
    /// `locator` 和 `options` 按值移入遍历生命周期。根本身不作为项目返回；
    /// 直接子项深度为一。创建期错误由 Future 返回，遍历期错误由流返回。
    /// 遍历不会跟随目录链接；已经产出的目录在下降前被链接替换时也不得进入
    /// 链接目标。遍历不取得库级目录冻结，也不承诺顺序、快照一致性或对并发
    /// 创建、删除、改名的唯一观察；平台仍可因活动枚举资源拒绝某次名称操作。
    /// 需要稳定视图时，调用方须另行建立协调或快照协议。
    fn walk<'a>(
        &'a self,
        locator: Self::Locator,
        options: WalkOptions,
    ) -> impl Future<Output = pi_result::Result<Self::WalkStream<'a>>>
           + Send
           + 'a;

    // 严格创建一个单层目录，并在最终位置已经存在任意条目时失败。
    //
    // 本方法是 namespace 的单目标目录创建入口。它只尝试建立 `locator`
    // 表示的一个目录，不递归创建缺失的祖先，不创建初始文件，也不打开目录
    // 流或建立文件监听。父目录或远端等价容器必须已经存在。
    //
    // 本接口采用严格创建语义：最终位置已经存在目录、普通文件、符号链接、
    // 悬空符号链接、Windows 重解析点或其它特殊对象时都失败。已经存在的
    // 目录不会被当作幂等成功；调用方需要“保证目录存在”的递归语义时必须
    // 使用以后单独冻结的接口，并处理它不同的部分副作用合同。
    //
    // # 参数、借用与成功值
    //
    // `locator` 只在返回 Future 的 `'a` 生命周期内共享借用，不被消费。目录
    // 创建成功后没有活动文件资源、目录游标、映射 guard 或其它必须交付的
    // 公开资产，因此成功值为 `()`。调用方需要新目录的元信息或内容流时，
    // 必须在成功后显式调用 [`Self::metadata`] 或 [`Self::read_dir`]，并接受
    // 两次操作之间正常存在的并发变化。
    //
    // 借用 locator 避免每次单目录创建都强制复制可能较大的路径或 URL。
    // adapter 只有在同步创建任务、远端请求或取消后的完成者必须脱离调用栈
    // 时才可克隆拥有型 locator；克隆只复制位置表示，不能复制 backend、
    // 认证上下文或活动资源。
    //
    // 本方法不接收权限、Unix mode、Windows ACL、安全描述符、远端标签或
    // backend 专有属性。标准 adapter 使用自己的默认目录创建属性。若安全
    // 属性必须与目录建立原子生效，调用方不能先创建后修改并假定中间窗口
    // 安全；相应能力必须通过以后经过跨平台调研的独立接口提供。
    //
    // # 父目录、符号链接与严格创建
    //
    // 最终路径分量不得预先存在，且不得跟随最终符号链接创建其目标。本地
    // adapter 必须使用平台单目录创建原语直接表达该条件，不能先调用
    // [`Self::try_exists`] 再创建；先检查后创建会留下检查与使用时间差竞态。
    //
    // 路径中间分量仍按 adapter 公开的正常路径解析规则处理。中间符号链接、
    // Windows 重解析点、挂载变化和父目录替换可能影响最终解析结果；本方法
    // 不因此成为路径沙箱，也不承诺抵御不合作参与者对祖先目录的并发修改。
    // 无效路径、缺失父目录、父对象不是目录或容器、链接循环及越出 adapter
    // 允许范围必须返回明确错误，不能隐式创建、修复或规范化父层级。
    //
    // 本地单目录创建系统调用成功建立最终目录项的时刻是创建提交点。具有
    // 真实目录或容器语义的远端 backend 必须使用自己的原子单目标创建条件；
    // 无法避免客户端先检查后创建竞态时必须在产生目标副作用前返回“不支持”。
    //
    // # 错误与目标副作用证据
    //
    // 普通失败使用 [`CreateFailure`]，把 [`pi_result::Error`] 与
    // [`crate::CreateTargetEvidence`] 放在同一个错误分支中：
    //
    // - 参数、locator、父目录、能力或权限检查在创建提交前失败，以及底层
    //   明确报告目标已经存在时，使用
    //   [`crate::CreateTargetEvidence::NotCreatedByOperation`]；
    // - 能够证明目录已经由本次操作建立，但随后结果转换或完成交付失败时，
    //   使用 [`crate::CreateTargetEvidence::CreatedByOperation`]；
    // - 远端提交响应丢失或 backend 确实无法证明提交结果时，使用
    //   [`crate::CreateTargetEvidence::Unknown`]。
    //
    // 证据只描述本次操作是否跨过创建提交点，不证明错误返回时目标仍存在、
    // 仍位于相同 locator、仍是同一个对象或尚未被其它参与者修改。adapter
    // 不得为了把失败恢复成“未创建”而自动删除已经建立的目录；该目录可能
    // 已被其它线程、进程、监听器或远端参与者观察和使用。
    //
    // 目标已存在、父目录不存在、对象种类错误、权限不足、只读文件系统、
    // 名称或路径非法、后端不支持、空间或配额不足、资源耗尽、远端协议错误
    // 和底层 I/O 失败都必须结构化返回。满足接口前置条件的可报告情况不得
    // panic，也不能被折叠为一个无法判断是否可重试的布尔结果。
    //
    // # 远端目录能力
    //
    // 具有可观察、可枚举和可删除的真实目录或容器创建合同的远端 adapter
    // 可以实现本方法。只有字符串前缀、无需显式建立目录的对象存储默认不
    // 具有该能力，必须返回“不支持”，不能为了让统一接口看似成功而私自创建
    // 含义不稳定的目录标记对象。
    //
    // backend 若正式定义了目录标记对象，只有在其创建、存在性、枚举、删除、
    // 冲突和一致性语义均能满足本合同，并公开与本地目录的差异时才能采用。
    // 一个 URL 的文本形状或尾部斜杠本身不能证明远端目录创建能力。
    //
    // # 并发、目录流与文件协调
    //
    // 同一进程内，本方法必须在底层创建前非阻塞地取得“物理父 namespace、
    // 最终名称”对应的拥有型排它许可；同名创建、`copy_new` 目标预留、安全
    // 删除、改名或其它 namespace 写操作已经持有许可时，本次调用在副作用前
    // 返回冲突。不同名称使用不同许可，不由一把进程级路径锁串行化。
    //
    // 该许可不能替代底层原子目录创建条件。不合作进程、远端参与者或库外
    // 调用仍由底层原子原语决定唯一成功者；成功者以外的调用按真实结果返回
    // 目标已存在或其它错误。
    //
    // 活动 [`Self::DirectoryStream`] 或 [`Self::WalkStream`] 可以观察到创建前
    // 或创建后的目录状态，也可能受底层并发枚举语义影响而遗漏或重复观察；
    // 本方法不为既有流建立快照、通知或重扫。需要变化事件的调用方必须使用
    // 以后单独冻结的 `FileWatch` 接口并处理其丢失事件合同。
    //
    // 本方法不打开普通文件，不读取或修改文件内容，不建立 MMAP，也不取得
    // 文件稳定身份协调核心中的读取、追加、覆盖、截断或映射租约。目录本身
    // 不进入 [`FileIo`] 能力域。普通调用也不创建跨进程协调 sidecar、协议
    // 文件或 `fs4` 锁。
    //
    // # 取消、阻塞隔离与资源清理
    //
    // 从未轮询的 Future 不得解析远端容器、提交系统调用或创建目标。创建
    // 任务一旦提交，调用方丢弃 Future 只表示停止等待；已经进入同步系统
    // 调用或远端提交的工作通常不能由 Rust Future 抢占。内部拥有型完成者
    // 必须继续到安全停止点，释放临时句柄、请求和准入状态，不得访问已经
    // 结束的调用方借用。
    //
    // 取消没有返回 [`CreateFailure`] 的通道，因此调用方在提交点不确定时
    // 必须按“目录可能已经创建”处理，并按需要重新查询；不得盲目重试并把
    // `AlreadyExists` 当作本次取消一定成功或一定失败的证明。后台收尾不会
    // 自动删除已经建立的目录，也不提供事务回滚。
    //
    // 本地路径解析和目录创建可能阻塞，网络挂载尤其可能具有长尾延迟；这些
    // 工作必须由 adapter 的有界阻塞设施承载，不能长期占用调用方执行器的
    // poll 线程。返回 Future 为 `Send + 'a`，可以在 namespace 与 locator
    // 的共享借用期内跨线程迁移，但不绑定任何具体异步运行时。
    //
    // # 副作用、幂等性、持久性与成本
    //
    // 本方法会修改 namespace，可能建立本地目录或远端等价目标，并产生系统
    // 调用、请求、临时分配、日志和指标，因此不是纯函数。一次成功后以相同
    // locator 重试通常返回“已存在”，所以既不是状态幂等操作，也不是响应
    // 幂等操作；结果未知时直接重试不能恢复第一次调用的准确结果。
    //
    // 成功只表示普通创建原语完成，不隐式刷新新目录或父目录，也不保证目录
    // 项和元信息在掉电、操作系统崩溃、失信硬件缓存或硬件损坏后仍然存在。
    // 需要命名空间持久性证据的调用方必须使用以后单独冻结且平台能力足够的
    // 目录刷新或发布协议，不能把本方法成功等同于抗故障提交。
    //
    // 本地成本通常为 `O(P)` 路径解析和一次目录创建系统调用，`P` 是路径
    // 长度或组件数；远端通常至少需要一次条件创建请求。接口不承诺固定延迟、
    // 零分配、零系统调用、零网络请求或无阻塞。
    /// 严格创建一个单层目录。
    ///
    /// 父层必须已经存在；本方法不递归创建祖先。最终位置存在任何对象时均
    /// 失败。成功只说明该目录已在正常运行语义下建立，不隐含持久化屏障。
    /// 错误通过 [`CreateFailure`] 报告本次调用是否已经创建目标。
    fn create_dir<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), CreateFailure>>
           + Send
           + 'a;

    // 确保定位符解析到的完整目录层级存在，逐层创建所有缺失目录。
    //
    // 本方法是 namespace 的递归目录层级创建入口。与严格的
    // [`Self::create_dir`] 不同，已经存在且能按 adapter 正常路径规则解析为
    // 目录的层级满足要求；只有缺失层级才会提交创建。最终目标已经是目录时
    // 正常成功，不会为了制造“本次确实创建过”的表象而重复修改它。
    //
    // 本方法不创建普通文件，不删除、覆盖或替换冲突对象，也不会在后续层级
    // 失败时回滚此前创建的祖先目录。每一层创建都有独立提交点，整条目录树
    // 不是原子事务。
    //
    // # 参数、借用与返回值
    //
    // `locator` 只在返回 Future 的 `'a` 生命周期内共享借用，不被消费。成功
    // 值为 `()`，因为操作结束后没有活动目录句柄、游标、映射 guard 或其它
    // 必须交付的公开资源。需要元信息或枚举结果时，调用方必须随后显式查询，
    // 并接受两次操作之间正常存在的并发变化。
    //
    // 借用 locator 避免每次调用都强制复制完整路径或 URL。实现仍须为每个
    // 已经提交创建的逻辑层级构造拥有型 `Self::Locator`，以便后续失败时放入
    // [`CreateDirectoriesFailure`]。阻塞任务、远端请求或取消后的完成者必须
    // 脱离调用栈时，adapter 还可以显式克隆输入位置；这种复制只能发生在
    // 实际需要拥有状态的路径上。
    //
    // 本方法不接收目录权限、Unix mode、Windows ACL、安全描述符、远端标签
    // 或 backend 专有属性。每个新目录使用 adapter 的默认创建属性；已经存在
    // 的目录不会被修改成这些默认值。需要把安全属性与每层创建原子绑定的
    // 场景必须使用以后经过独立设计的接口，不能假定“递归创建后再修改”没有
    // 可观察窗口。
    //
    // # 目录层级、锚点与非目标
    //
    // 本方法只处理当前 namespace 根内部由 locator 表达的逻辑目录分量。
    // 原生绝对路径根、相对路径所依赖的 namespace 基准、远端 URL 的 scheme
    // 和 authority、bucket、账户或 adapter 配置的容器锚点都不由本方法自动
    // 创建。空表示、根表示和相对基准是否合法，由具体 locator 与 namespace
    // 已公开的解析合同决定；能解析到一个已有目录根时可以正常成功。
    //
    // 任一层存在普通文件、设备、管道或其它不能解析为目录的对象时必须失败，
    // 不能删除、改名或覆盖该对象后继续。父层权限不足、只读文件系统、越出
    // 配置根或路径语法无效也必须在相应层停止，不能私自规范化成另一个目标。
    //
    // 本方法只保证路径解析意义上的目录层级存在，不打开并长期锚定每一层
    // 原生目录身份，不承诺提供一个阻止祖先替换的安全沙箱。需要不跟随链接、
    // 抵御不合作目录替换或限制在预先打开根句柄下的能力，应以后设计独立的
    // handle-relative 安全接口。
    //
    // # 符号链接与 Windows 重解析点
    //
    // 已存在的中间符号链接按 adapter 的普通路径规则解析。它指向目录时可以
    // 继续；悬空、形成循环、指向非目录或越出 adapter 允许范围时返回错误。
    // 最终位置是指向目录的符号链接时也满足本方法的“可以解析为目录”目标。
    //
    // 这与 [`Self::create_dir`] 的严格最终条目语义不冲突：后者要求最终位置
    // 不存在任何条目，因此符号链接一定是已存在冲突；本方法则接受已经满足
    // 目录解析语义的路径。
    //
    // Windows 重解析点不全部等价于符号链接。adapter 只有在能够证明某种
    // 重解析点可安全地进入其普通目录解析合同后才能继续；未知、越界或可能
    // 改变 namespace 归属的类型必须保守失败，不能一律当作普通目录。
    //
    // # 分层提交、并发创建与重新核验
    //
    // 每个缺失目录由一次原生或远端单层创建操作提交，整个调用没有跨层原子
    // 提交点。另一个参与者可能在检查后抢先创建同一层；底层返回“已存在”时，
    // adapter 必须重新确认该位置当前能解析为目录，再继续下一层，不能仅凭
    // 错误代码把普通文件、悬空链接或其它对象当成成功目录。
    //
    // 同一进程内，每次提交缺失层级前都必须按该层的物理父 namespace 与最终
    // 名称非阻塞取得拥有型排它许可，并在单层提交得到确定结果后释放。它与
    // 同名 `copy_new` 目标预留、安全删除、改名和其它 namespace 写操作冲突，
    // 但不能跨整条递归调用长期锁住已经存在的祖先，也不能替代底层原子创建
    // 条件。不同名称和无路径依赖的其它分支仍可并行。
    //
    // 由并发参与者创建而被本次操作接受的目录不属于本次副作用，不能进入
    // 失败载体的任何证据列表。已经确认的目录仍可能在下一步之前被删除、
    // 改名或替换；后续解析必须按实际观察继续或失败，本接口不建立整条路径
    // 的稳定身份快照。
    //
    // 一旦某层不能被可靠确认为目录或创建结果无法确定，顺序实现不得再尝试
    // 更深目标。远端一次原子或不可拆分批量请求可能已经同时提交多层，因此
    // 失败载体允许多个不确定目标，但 adapter 不能把请求未覆盖的剩余层级
    // 虚报为已经提交。
    //
    // # 失败、部分副作用与恢复资产
    //
    // 普通失败使用 [`CreateDirectoriesFailure<Self::Locator>`]。其中：
    //
    // - `confirmed_created` 按祖先到后代记录本次操作得到明确创建成功结果的
    //   逻辑 locator；
    // - `uncertain_targets` 按相同顺序记录已经提交创建、但 backend 无法证明
    //   是否成功的逻辑 locator；
    // - 调用前已经存在、由并发参与者创建或从未尝试的目录不进入任一列表。
    //
    // 这些 locator 是历史位置证据，不是稳定对象身份。失败返回时，目标可能
    // 已经被其它参与者填入内容、删除、改名或替换。调用方不能根据列表直接
    // 执行无条件补偿删除；恢复必须重新查询并建立自己需要的身份和空目录
    // 前置条件。
    //
    // adapter 不得自动回滚已经创建的祖先目录。即使它们最初为空，创建后也
    // 可能被另一个线程、进程、文件监听器或远端参与者观察和使用；逆序删除
    // 既不能恢复原子性，还可能删除不再属于本次操作的 namespace 条目。
    //
    // 无效定位符、非目录冲突、权限不足、链接错误、只读文件系统、后端能力
    // 不足、空间或配额耗尽、远端协议错误和底层 I/O 失败均通过载体中的
    // [`pi_result::Error`] 诊断。可报告情况不得 panic，也不能为了返回简单
    // 错误而丢弃已经发生的多目标副作用证据。
    //
    // # 远端目录与纯前缀 backend
    //
    // 具有真实层级目录、容器或正式目录标记合同的远端 adapter 可以逐层或
    // 批量实现本方法，但必须如实报告每个提交目标。目录标记只有在创建、
    // 存在性、枚举、删除、冲突和一致性语义均有正式定义时才能被当作目录，
    // 不能仅依据 URL 文本或尾部斜杠猜测。
    //
    // 对无需显式建立目录的纯对象前缀 backend，adapter 可以在确认 locator
    // 属于合法层级语义后返回成功，但不得声称创建了并不存在的目录对象，也
    // 不得把任何 locator 填入 `confirmed_created`。backend 无法提供可靠层级
    // 解析时必须返回“不支持”，不能把任意字符串前缀冒充完整 POSIX 目录树。
    //
    // # 取消、阻塞隔离与资源生命周期
    //
    // 从未轮询的 Future 不得查询或创建任何层级。取消可能发生在任意单层
    // 提交点之间；已经进入同步系统调用、远端请求或不可抢占批量操作的工作
    // 必须由拥有型完成者安全收尾，不得在 Future Drop 后访问 namespace 或
    // locator 的失效借用。
    //
    // Drop 可以阻止尚未提交的更深层创建，但不能保证抢占已经提交的工作。
    // 因而取消后可能没有副作用、留下部分祖先，或者已经建立完整层级。取消
    // 没有返回 [`CreateDirectoriesFailure`] 的通道，调用方必须重新查询，不能
    // 根据随后一次 `AlreadyExists` 推断第一次调用的准确完成点。
    //
    // 后台收尾只释放临时句柄、请求、buffer 和准入状态，不执行补偿删除或
    // 事务回滚。可能阻塞的本地路径操作必须由 adapter 的有界阻塞设施承载，
    // 不能长期占用调用方执行器的 poll 线程。Future 为 `Send + 'a`，不绑定
    // Tokio、async-std、smol、Monoio 或其它具体运行时。
    //
    // # 文件协调、流与监控边界
    //
    // 本方法不打开普通文件、不读写文件内容、不建立 MMAP，也不取得文件
    // 稳定身份协调器中的读取、追加、覆盖、截断或映射租约。遇到已有普通
    // 文件只会失败，不修改它。普通递归建目录也不创建跨进程协调 sidecar、
    // 协议文件或 `fs4` 锁。
    //
    // 活动目录流或递归遍历流可能观察到部分建立过程、完整层级或底层允许的
    // 遗漏与重复，本方法不向既有流提供快照或重扫。以后单独冻结的文件监听
    // 只能报告后端真实事件，同样不能把多层创建提升为原子单事件。
    //
    // # 副作用、幂等性、持久性与成本
    //
    // 本方法修改 namespace，并可能发起多次系统调用或远端请求、分配路径和
    // 证据状态、使用阻塞设施、记录日志与指标，因此不是纯函数。在 namespace
    // 稳定且权限不变时，重复调用具有目标状态幂等特征：已有目录不会重复
    // 创建；并发变化、远端一致性和失败副作用仍可令不同调用获得不同响应，
    // 因而不承诺严格响应幂等性。
    //
    // 成功只表示操作结束时整条 locator 能完成目录解析，不隐式刷新每个新
    // 目录或其父目录，也不提供掉电、操作系统崩溃、失信硬件缓存或硬件损坏
    // 后的持久性保证。
    //
    // 设逻辑深度为 `D`，本地实现通常需要 `O(D)` 次层级检查或创建。失败
    // 证据为 `C` 个已提交目标保存至少 `O(C)` 个拥有型 locator；对于逐层
    // 复制路径前缀的 `PathBuf` 或 URL，累计文本内存最坏可能高于线性，这是
    // 精确报告多目标副作用的显式成本。实现不得持有同步锁跨越 `.await`、
    // 文件系统调用或网络请求，也不得用无界并发预取掩盖路径依赖关系。
    /// 确保定位符表示的完整目录层级存在。
    ///
    /// 已存在且最终能够解析为目录的层级满足要求，包括能够解析到目录的链接；
    /// 缺失层级按依赖顺序创建。某一级最终解析为文件、悬空链接或其它非目录
    /// 对象时失败。本方法不会删除、覆盖或替换对象。失败通过
    /// [`CreateDirectoriesFailure`] 精确报告已确认创建的层级；不会自动回滚已
    /// 创建目录，取消后也可能留下合法的部分层级。
    fn create_dir_all<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<
        Output = pi_result::RawResult<
            (),
            CreateDirectoriesFailure<Self::Locator>,
        >,
    > + Send
           + 'a;

    // 排它地移除一个普通文件、远端文件对象或最终符号链接。
    //
    // 本方法是当前进程受管协调域中的安全默认单文件移除入口。它在提交底层
    // 移除前按稳定文件身份证明不存在任何公开文件资源、映射或在途操作，并
    // 原子登记排它删除租约。任一冲突都会立即返回，不等待资源 Drop。
    //
    // 本方法采用严格存在语义：目标不存在时返回错误，不把“已经不存在”当作
    // 幂等成功。目标是目录时返回类型错误，不能隐式切换为目录删除。首版本地
    // 保证域只包含普通文件和最终符号链接；设备、管道、套接字及其它特殊对象
    // 默认返回“不支持”或准确的对象种类错误。
    //
    // # 参数、借用与返回值
    //
    // `locator` 只在返回 Future 的 `'a` 生命周期内共享借用，不被消费。成功
    // 值为 `()`，因为移除完成后没有文件资源、句柄或 guard 可以合法交付。
    // 需要保留位置供审计或后续查询的调用方继续拥有原 locator；但该位置不
    // 是稳定身份，成功后可以被其它参与者立即用于创建新对象。
    //
    // Future 为 `Send + 'a`，可以在 namespace 与 locator 的共享借用期内跨
    // 工作线程迁移，不绑定 Tokio、async-std、smol、Monoio 或其它运行时。
    // adapter 只有在阻塞任务、远端请求或取消后的完成者必须脱离调用栈时才
    // 可以显式克隆拥有型 locator。
    //
    // # 最终符号链接、目录与硬链接
    //
    // 最终路径分量是符号链接时，移除链接自身，不跟随并删除其目标。中间
    // 分量仍按 adapter 的普通路径规则解析；本方法不是路径沙箱。Windows
    // 重解析点只有被 adapter 可靠识别为本接口支持的最终符号链接时才按相同
    // 规则移除，未知重解析类型必须保守失败。
    //
    // 普通目录必须由独立目录删除方法处理。即使目录为空，本方法也不能根据
    // 平台错误差异偷偷改用 `rmdir`。最终链接指向目录时仍然只移除链接本身，
    // 因为最终分量不跟随。
    //
    // 普通文件可能有多个硬链接。协调准入按底层稳定身份汇合，因此通过另一
    // 硬链接打开的受管 [`FileIo`] 同样阻止本方法；删除成功只解除本 locator
    // 的名称绑定，其它硬链接继续存在。成功证据不能被解释为底层对象或全部
    // 数据已经销毁。
    //
    // # 进程内排它准入
    //
    // 内置本地 adapter 必须按以下逻辑次序进入删除：
    //
    // 1. 解析并锚定物理父 namespace；
    // 2. 按父目录稳定身份与最终名称取得短期进程内条目门禁；
    // 3. 不跟随最终链接地识别目标类型；
    // 4. 普通文件通过内部探测句柄取得稳定文件身份；
    // 5. 与进程级分片稳定身份注册表中的唯一协调核心汇合；
    // 6. 在线性化临界区内检查全部资源和操作计数，并登记拥有型删除租约；
    // 7. 离开同步临界区后执行底层移除。
    //
    // 准入时必须同时证明：没有任何公开或候选 [`Self::File`]、只读或可写
    // MMAP、待建立映射、读取、追加、覆盖、截断、刷新、打开、删除、改名、
    // 替换及取消后仍在收尾的完成所有者，也没有当前跨进程 authority 协调域。
    // 任一状态存在都以 [`pi_result::ErrorKind::Conflict`] 在目标副作用前失败。
    //
    // “立即失败”只表示不排队等待冲突资源释放，不表示路径解析、身份查询或
    // 底层删除具有零延迟。取得删除租约后，新的资源打开和冲突操作也必须
    // 失败，直到本次提交或安全撤销完成。实现不能先读取一个可能过期的计数，
    // 释放锁后再无租约删除。
    //
    // 进程级注册表必须按稳定身份分片；准入不能扫描进程中的全部公开资源。
    // 同步临界区只允许计数、状态和租约转移，禁止文件或网络 I/O、`.await`、
    // 阻塞等待、用户回调、可能阻塞的日志和无界分配。跨异步阶段的权利必须
    // 由拥有型删除租约承载。
    //
    // # 路径身份与外部竞态边界
    //
    // `Self::Locator` 不能作为文件协调键。不同路径、符号链接或硬链接可以
    // 指向同一对象，相同路径也可以在相邻时刻指向不同对象。内置 adapter
    // 必须从打开后的内部句柄取得稳定身份，并在提交前重新核验父目录和最终
    // 条目仍对应候选对象。
    //
    // Linux 等平台没有通用的“按任意已打开文件句柄直接解除指定名称绑定”
    // 原语；实现应优先使用锚定父目录句柄的相对 `unlinkat` 等价操作，缩小
    // 路径竞态。同一进程内所有受管打开、创建、删除、改名和替换必须共享
    // 相同条目门禁，不能形成彼此不可见的锁域。
    //
    // 这些措施不能强制不合作进程、库外原生句柄、另一份未共享静态状态的库
    // 副本或恶意父目录参与者服从。本方法保证当前进程同一受管协调域内的
    // 排它性，不是跨进程安全证明或恶意路径沙箱。提交前发现身份变化必须
    // 失败；无法排除外部路径竞态的 adapter 必须公开收窄保证域。
    //
    // # 远端条件删除
    //
    // 远端安全 adapter 必须取得能够代表当前目标的可靠版本或稳定身份，并
    // 使用条件删除、版本删除或等价原语，保证提交针对的仍是已核验对象。
    // 只能按 locator 发出无条件删除、无法阻止并发替换的 backend 不能实现
    // 本方法，应在副作用前返回“不支持”；它仍可实现以后单独声明的
    // [`Self::remove_file_uncoordinated`]。
    //
    // 对象存储的版本保留、删除标记、回收站、延迟回收和合规策略必须如实
    // 保留。本方法成功只要求当前可见名称绑定或指定版本的移除已经被 backend
    // 不可撤销地接受，不能把服务端仍保留历史数据描述成物理销毁。
    //
    // # 错误与移除提交证据
    //
    // 普通失败使用 [`RemoveFailure`]，其中的 [`crate::RemoveTargetEvidence`]
    // 按真实底层提交点填写：
    //
    // - 资源或操作冲突、目标不存在、对象种类错误、权限不足、身份变化、
    //   backend 不支持以及其它提交前失败使用
    //   [`crate::RemoveTargetEvidence::NotRemovedByOperation`]；
    // - 底层已明确接受目标移除，随后发生结果转换、协调收尾或交付错误时使用
    //   [`crate::RemoveTargetEvidence::RemovedByOperation`]；
    // - 远端请求已经提交但响应丢失，确实无法证明结果时使用
    //   [`crate::RemoveTargetEvidence::Unknown`]。
    //
    // `NotRemovedByOperation` 不证明目标当前仍存在，`RemovedByOperation` 不
    // 证明相同 locator 尚未被重新使用，`Unknown` 必须按可能已经移除处理。
    // adapter 不得为了制造整洁失败外观而恢复、重建或删除其它硬链接。
    //
    // 实现不得在删除前持久修改权限、只读属性或 ACL 来强行通过检查。平台
    // 若提供与同一原子移除请求绑定且失败时不遗留元信息变化的属性忽略能力，
    // 可以作为内部实现细节；否则应返回准确权限错误。
    //
    // 目标不存在、类型错误、权限不足、活动资源冲突、只读文件系统、名称或
    // 路径非法、资源耗尽、远端条件失败、协议错误和底层 I/O 失败均进入统一
    // report。所有可报告情况不得 panic。
    //
    // # 完成点、物理存续与持久性
    //
    // 成功表示目标名称绑定已经移除，或 backend 已不可撤销地接受移除。它不
    // 保证底层字节立即销毁、空间立即回收、其它硬链接消失、远端历史版本被
    // 清理或不合作进程的句柄失效。
    //
    // Unix 在最后一个名称被移除后仍允许已打开描述符继续持有对象；Windows
    // 普通删除也可能受到已有句柄共享模式和删除等待状态影响。本方法通过
    // 受管资源计数排除库内旧资源，但无法控制外部句柄。其成功保证不得高于
    // 底层平台对不合作资源的真实能力。
    //
    // 成功不隐式刷新物理父目录、卷、远端目录索引或删除标记，也不提供掉电、
    // 操作系统崩溃、失信硬件缓存或硬件损坏后的持久性保证。需要命名空间
    // 持久性证据时必须使用以后单独冻结的平台能力。
    //
    // # 取消、重试与幂等性
    //
    // 从未轮询的 Future 不得打开探测句柄、登记租约或提交删除。底层移除
    // 一旦提交，调用方 Drop Future 只表示停止等待；拥有型完成者必须继续
    // 到安全停止点，关闭内部句柄、撤销或完成租约，不能访问已失效借用。
    //
    // 取消没有返回 [`RemoveFailure`] 的通道，因此目标可能仍存在、已经移除
    // 或结果未知。调用方必须重新查询并处理相同 locator 已经指向新对象的
    // 可能，不能盲目重试。严格删除不是状态或响应幂等操作：一次成功后直接
    // 重试通常返回目标不存在，未知结果下重试还可能删除后来创建的新对象。
    //
    // # 副作用与成本
    //
    // 本方法会修改 namespace，并可能打开内部探测句柄、查询稳定身份、更新
    // 进程内协调状态、执行系统调用或远端请求、分配临时状态并记录日志或
    // 指标，因此不是纯函数。
    //
    // 本地通常承担 `O(P)` 路径解析、一次稳定身份查询、期望 `O(1)` 的分片
    // 协调核心访问及一次删除系统调用；`P` 是路径长度或组件数。远端通常
    // 至少执行一次身份/版本查询和一次条件删除。接口不承诺零分配、零系统
    // 调用、零网络请求、固定延迟或无阻塞。
    //
    // # 参考基线
    //
    // 本合同于 2026-08-31 核验了 Linux man-pages 6.18 的
    // [`unlink(2)`](https://man7.org/linux/man-pages/man2/unlink.2.html)、
    // Microsoft 的
    // [`DeleteFileW`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-deletefilew)
    // 以及 Rust 1.96.1 标准库
    // [`std::fs::remove_file`](https://doc.rust-lang.org/std/fs/fn.remove_file.html)。
    // 本接口采用它们共同支持的“移除名称不等于立即物理销毁”事实，但增加
    // 当前进程受管资源为零的稳定身份排它准入；依赖升级或平台实现变化时
    // 必须重新核验该适配差异。
    /// 在当前进程的受管操作范围内排它移除一个文件名称。
    ///
    /// 提交移除前，若同一文件仍有受管资源、映射或冲突操作，本方法立即失败，
    /// 不等待它们释放。最终分量为符号链接时移除链接自身；目录不受支持。
    /// 成功表示名称移除已提交，不保证底层对象立即物理回收或已经持久化。
    /// [`RemoveFailure`] 说明本次调用可证明的提交结果。
    fn remove_file<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), RemoveFailure>>
           + Send
           + 'a;

    // 按 backend 原生生命周期语义移除文件，不进入本库的文件协调器。
    //
    // 本方法是 [`Self::remove_file`] 的显式非协调版本。它仍是安全 Rust 接口，
    // 但不查询或等待当前进程内的稳定身份资源、映射和在途操作，也不进入
    // 跨进程 authority 协议。调用方选择的是更弱的一致性与对象生命周期
    // 保证，不是绕过 Rust 内存安全、参数校验或资源清理。
    //
    // 方法采用严格存在语义：目标不存在时返回错误，不当作幂等成功。最终
    // 分量是符号链接时移除链接自身，目标是目录时返回类型错误。首版本地
    // 保证域仍只包含普通文件和可可靠识别的最终符号链接；“非协调”不会把
    // 设备、管道、套接字或未知 Windows 重解析点自动扩大为受支持目标。
    //
    // # 参数、借用与返回值
    //
    // `locator` 只在 Future 的 `'a` 生命周期内共享借用，不被消费。成功返回
    // `()`，不交付底层已删除对象或旧资源。原 locator 仍由调用方拥有，但
    // 删除后可以立即被并发参与者重新用于另一个对象，不能作为成功证据或
    // 稳定身份继续解释。
    //
    // Future 为 `Send + 'a`，不绑定具体异步运行时。阻塞 worker、远端请求
    // 或取消后的完成者必须脱离调用栈时，adapter 可以显式克隆拥有型位置；
    // 后台状态不得借用已经结束的 Future 栈帧。
    //
    // # “非协调”的精确范围
    //
    // 本方法明确不执行以下动作：
    //
    // - 不查询进程级稳定文件身份注册表；
    // - 不检查公开或候选 [`Self::File`] 的资源计数；
    // - 不检查活动/待建立 MMAP 或在途读取、追加、覆盖、截断和刷新；
    // - 不取得文件级删除租约，也不等待资源 Drop；
    // - 不检查目标是否已经进入跨进程 authority 协调域；
    // - 不阻止删除期间新的受管资源打开或操作进入。
    //
    // 它仍必须校验 locator 语法和 namespace/backend 归属，处理基本权限、
    // 最终对象种类和符号链接方向，准确分类错误，并保证内部句柄、映射、
    // 请求与取消完成者的 Rust 内存安全。“不检查协调状态”不能被实现成跳过
    // 输入验证、从同一 raw handle 重复构造所有者或提前释放映射 guard。
    //
    // # 提交目标与检查后使用竞态
    //
    // 删除对象是底层提交时 locator 实际解析到的名称绑定。本方法不预先绑定
    // 某个稳定文件身份，也不承诺提交对象仍是调用方此前通过 metadata、目录
    // 流或文件打开观察到的对象。并发改名、替换和重新创建可能使它删除另一
    // 个目标；这是明确公开的路径检查后使用竞态。
    //
    // adapter 可以使用锚定父目录的相对系统调用降低祖先路径漂移，但不能把
    // 该实现优化描述成稳定身份排它保证。同一进程内受管操作也不会因为本
    // 方法自动加入条目门禁；需要这种保证必须使用 [`Self::remove_file`]。
    //
    // 最终符号链接不跟随并删除其自身；中间分量仍按普通路径规则解析。本
    // 方法不是恶意路径沙箱。目标种类预检与实际移除之间仍可能被不合作参与者
    // 替换，adapter 必须公开其平台可达到的真实边界，不能用一次预检声称
    // 提交时对象身份已被锁定。
    //
    // # 已打开资源、硬链接与 MMAP
    //
    // 本方法可以在同一稳定对象仍有受管或外部文件资源时提交。删除名称不会
    // 主动关闭旧 [`FileIo`]、取消在途操作、解除映射、截断内容或使协调核心
    // 指向随后在同一 locator 创建的新对象。旧资源始终继续绑定它们原先的
    // 底层身份，新目标必须在以后打开时取得自己的新身份和协调核心。
    //
    // Unix 上，解除最后一个名称绑定后，打开描述符和映射仍可使底层对象存活
    // 到最后一个引用关闭；通过其它硬链接也仍可访问同一对象。Windows 可能
    // 因已有句柄的 share-delete 模式或活动映射拒绝删除，也可能先进入等待
    // 句柄关闭的删除状态。远端已有读取、追加或上传会话可以继续、失败或与
    // 删除竞争，取决于 backend 的真实版本与请求合同。
    //
    // 无论平台结果如何，旧公开资源都必须保持 Rust 内存安全：不得产生悬垂
    // 引用、双重关闭、提前解映射或后台任务访问已释放状态。删除名称本身不得
    // 被 adapter 偷换成截断或原地重写。若某个平台或 backend 不能在活动映射
    // 存在时安全删除，它必须让底层操作失败，不能为了兑现“非协调”而强行
    // 绕过系统保护。
    //
    // # 远端无条件删除与严格不存在错误
    //
    // 本方法不要求先取得稳定版本，也允许 backend 使用其普通无条件删除。
    // 但公共合同仍要求目标不存在时返回错误。远端 API 若把删除不存在对象
    // 固定处理为成功，adapter 只有在能够通过可靠条件请求或等价结果区分时
    // 才能实现该严格语义；先检查再无条件删除不能消除并发竞态。无法满足时
    // 应返回“不支持”，不能伪造“本次确实移除了目标”的成功。
    //
    // 版本保留、删除标记、回收站和延迟回收属于 backend 原生语义。成功不
    // 表示历史版本、底层数据或配额占用已经清除。
    //
    // # 跨进程协调承诺
    //
    // 本方法不会因为目标处于跨进程 authority 域而自动拒绝。若调用方此前
    // 在 `unsafe` authority 建立入口承诺所有参与者和 namespace 操作遵守
    // 同一协议，随后调用本方法绕过协议，就违反了此前的安全合同。本方法
    // 不能作为协调式删除的内部降级路径，也不能描述为跨进程安全删除。
    //
    // 这种违反通常首先破坏身份、顺序和产品一致性保证；实现仍必须保证安全
    // Rust 调用本方法本身不会直接制造未定义行为。任何真正依赖外部合作才能
    // 维持的内存安全前置条件都必须继续由原 `unsafe` 授权合同承担。
    //
    // # 错误与移除提交证据
    //
    // 普通失败仍使用 [`RemoveFailure`]：
    //
    // - 底层明确在提交前拒绝移除时使用
    //   [`crate::RemoveTargetEvidence::NotRemovedByOperation`]；
    // - 底层已明确接受移除，随后发生结果转换或交付错误时使用
    //   [`crate::RemoveTargetEvidence::RemovedByOperation`]；
    // - 远端提交响应丢失或其它真实完成不确定性使用
    //   [`crate::RemoveTargetEvidence::Unknown`]。
    //
    // 本方法不执行补偿恢复、不重建目标、不删除其它硬链接，也不因旧资源仍
    // 可操作就把一个已经成功的名称移除改写为失败。所有可报告的路径、类型、
    // 权限、平台共享冲突、远端协议和 I/O 错误都必须结构化返回，不得 panic。
    //
    // # 完成点、取消与重试
    //
    // 成功表示名称绑定已经被底层移除或 backend 已不可撤销地接受该动作，
    // 不保证文件立即物理删除、空间立即回收、旧句柄失效或远端历史版本消失。
    // 也不隐式刷新父目录或提供抗掉电、系统崩溃及硬件损坏保证。
    //
    // 从未轮询的 Future 不得提交删除。提交后取消可能留下已经移除的目标；
    // 拥有型完成者必须安全收尾，不能访问失效借用。取消没有证据返回通道，
    // 调用方必须重新查询。严格删除不具备状态或响应幂等性，未知结果下盲目
    // 重试可能删除后来在相同 locator 创建的新对象。
    //
    // # 副作用与成本
    //
    // 本方法会修改 namespace，并可能执行路径解析、系统调用或远端请求、
    // 分配临时状态、使用阻塞设施并记录日志和指标，因此不是纯函数。
    //
    // 本地通常承担 `O(P)` 路径解析和一次删除系统调用，不承担稳定身份注册表
    // 查询或等待资源释放；`P` 是路径长度或组件数。可能阻塞的系统调用仍须
    // 由有界阻塞设施承载。“不等待协调资源”不等于能够抢占已经提交的系统
    // 调用或不等待远端响应。
    //
    // # 参考基线
    //
    // 本合同于 2026-08-31 核验了 Linux man-pages 6.18 的
    // [`unlink(2)`](https://man7.org/linux/man-pages/man2/unlink.2.html)、
    // Microsoft 的
    // [`DeleteFileW`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-deletefilew)
    // 以及 Rust 1.96.1 标准库
    // [`std::fs::remove_file`](https://doc.rust-lang.org/std/fs/fn.remove_file.html)。
    // 本方法刻意保留这些平台对打开句柄和物理删除时机的差异，只增加统一的
    // 内存安全、错误证据与最终链接方向合同；依赖或平台变化时必须复核。
    /// 按底层平台或后端的原生生命周期语义移除一个文件名称。
    ///
    /// 本方法不与本库内其它已打开资源和操作建立排它顺序，因此正在使用该
    /// 对象的句柄可能继续有效，也可能使删除被平台拒绝；该接口始终保证
    /// Rust 内存安全。最终分量为链接时移除链接自身，目录不受支持。成功不
    /// 保证立即物理回收；[`RemoveFailure`] 报告可证明的提交结果。
    fn remove_file_uncoordinated<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), RemoveFailure>>
           + Send
           + 'a;

    // 排它地移除一个已经存在的空目录。
    //
    // # 作用与接口层级
    //
    // 本方法是当前进程受管协调域中的安全默认单目录移除入口。它只移除
    // locator 对应的一个空目录名称，不递归、不删除任何子项，也不把目录
    // 转换成文件删除。目标不存在、不是目录或在底层提交点仍然非空时必须
    // 返回错误。
    //
    // 名称沿用 Rust 标准库的 `remove_dir`；“只能删除空目录”是本接口的
    // 强制语义，而不是可选模式。本 crate 不提供 `remove_dir_all` 或其它
    // 递归目录树删除接口，也不能通过布尔参数、选项或隐式回退把多目标删除
    // 混入本方法。确需清理目录树的上层调用方必须显式枚举、逐项选择操作并
    // 自行处理部分进度、并发变化和恢复策略。
    //
    // # 参数、借用与返回值
    //
    // `locator` 在返回 Future 的 `'a` 生命周期内共享借用，不被消费。成功
    // 只返回 `()`，因为目录绑定移除后没有目录句柄或 guard 可以合法交付。
    // 调用方继续拥有原 locator，但它只是位置表示；成功后同一位置可以被
    // 其它参与者用于创建另一个目录、文件或其它 backend 对象。
    //
    // Future 为 `Send + 'a`，可以在 namespace 与 locator 的借用期内跨工作
    // 线程迁移，不绑定 Tokio、async-std、smol、Monoio 或其它运行时。只有
    // 阻塞任务或取消后的完成者必须脱离调用栈时，adapter 才需要克隆拥有型
    // locator；该克隆不构成稳定目录身份证明。
    //
    // # 类型、最终符号链接与根目录
    //
    // 最终路径分量必须解析为本接口支持的真实目录。最终分量是普通符号链接、
    // 悬空符号链接、Windows 重解析点或其它非目录对象时，本方法不得跟随其
    // 目标，也不得删除链接自身；应返回准确类型或不支持错误。删除链接自身
    // 必须使用 [`Self::remove_file`] 或明确选择更弱协调语义的对应入口。
    //
    // 中间路径分量仍按 adapter 的正常解析规则处理，本方法不是路径沙箱。
    // namespace 根、文件系统挂载点、卷根、进程当前工作目录或平台保留目录
    // 可以因平台规则返回忙、权限或无效操作错误；实现不能通过切换工作目录、
    // 卸载文件系统或修改权限来强制删除。
    //
    // # 空目录条件与线性化点
    //
    // adapter 必须使用平台或 backend 提供的原生“仅删除空目录”原语作为
    // 最终提交点。不能先调用 [`Self::read_dir`] 判断为空，再调用一个不带
    // 空目录前置条件的通用删除；枚举完成与删除之间可以并发加入新子项，
    // 这种检查与使用时间差无法证明提交时仍为空。
    //
    // 本地实现应使用锚定父目录句柄的相对 `rmdir` 等价能力或平台正式空目录
    // 删除原语，以底层原语成功的瞬间作为名称绑定移除提交点。并发旁路进程
    // 在提交前建立子项时，原生删除必须失败为非空或相应竞态错误；底层删除
    // 先成功时，旁路创建必须自行处理父目录已经消失。该竞态不能产生 Rust
    // UB，也不能促使本库递归清理后来出现的子项。
    //
    // # 进程内父条目与目录内容退役许可
    //
    // 内置本地 adapter 必须按以下逻辑次序进入删除：
    //
    // 1. 解析并锚定物理父 namespace；
    // 2. 按父目录稳定身份与最终名称非阻塞取得进程内父条目拥有型许可；
    // 3. 不跟随最终分量地打开并核验目标目录，取得稳定目录身份；
    // 4. 在该目录的进程内协调核心中非阻塞登记排它内容退役许可；
    // 5. 重新核验父目录、最终条目和目标稳定身份；
    // 6. 离开同步临界区后调用原生空目录删除；
    // 7. 完成或安全失败后按相反顺序释放许可。
    //
    // 父条目许可与同一名称上的创建、删除、改名和替换互斥。内容退役许可与
    // 正在创建、删除、改名或替换该目录直接子项的当前进程操作互斥；成功
    // 登记后，新的受管子项变更必须立即失败，直到删除完成或安全撤销。任何
    // 冲突都不排队等待，不自动取消或关闭另一个调用。
    //
    // 内容退役许可只统计目录条目的 namespace 变更，不统计任何普通文件
    // 内容访问。活动或在途的 [`Self::File`]、随机读取、顺序读取、严格追加、
    // 刷新、截断、覆盖、文件 MMAP 及其透明句柄都不与本方法冲突，本方法也
    // 不查询或扫描文件稳定身份注册表。如果一个可见子文件仍在目录中，原生
    // 空目录删除自然会以非空失败；如果其名称此前已经移除，仍存活的拥有型
    // 文件句柄或映射继续管理底层对象，不再构成该目录的 namespace 子项。
    //
    // 取得的是可以跨异步阶段持有的拥有型许可，不是跨 `.await` 持有同步
    // mutex guard。同步临界区只允许稳定身份比较、状态检查、计数和许可转移；
    // 其中禁止文件 I/O、`.await`、用户回调、可能阻塞的日志和无界分配。
    // 禁止反向取锁或原地升级共享许可。多目录操作必须在以后相应 API 中按
    // 统一稳定顺序取得全部相关许可，不能与本方法形成相反锁序。
    //
    // # 目录流、递归遍历和监听
    //
    // [`Self::DirectoryStream`]、[`Self::WalkStream`] 和以后声明的文件监听
    // 资源不进入内容退役计数，也不阻止本方法。它们是非快照观察者，不是
    // namespace 锁：以目标为根的浅层流可以结束或返回明确错误；以目标为根
    // 的递归流遇到根级失败时终止；从祖先开始的递归流可以按 [`Self::walk`]
    // 合同报告局部错误并继续；监听只能报告 backend 实际提供的变化事件。
    //
    // 流项目拥有自己的 [`DirectoryEntry`] 或 [`WalkEntry`] 数据，删除目录
    // 不得使已经交付的 Rust 值失效。adapter 必须尽量用允许 namespace 删除
    // 的共享模式打开目录枚举和监听资源；平台仍因活动原生句柄拒绝删除时，
    // 本方法返回准确占用或权限错误，不能强制关闭调用方流，也不能把失败改写
    // 成成功。
    //
    // 该选择不提供一致性快照。需要“遍历期间目录树不变”的调用方必须在更
    // 高层建立自己的事务、版本或全局协调，不能依赖一个长期目录流隐式冻结
    // namespace。
    //
    // # 进程、跨进程和远端边界
    //
    // 本方法的父条目和内容退役许可只协调当前进程中共享本库注册状态的
    // adapter。它不创建跨进程 sidecar、协议记录或 `fs4` 锁，不能阻止另一
    // 进程、另一份未共享静态状态的库副本或库外原生调用并发修改目录。
    // 底层原生空目录条件仍保证这些竞态不会被本库误实现成递归删除。
    //
    // 远端 adapter 只有在 backend 具有明确的目录对象或容器语义，并能保证
    // 删除提交时目录为空时才能实现本方法。纯对象前缀、最终一致枚举后进行
    // 无条件标记删除，或无法区分空目录与字符串前缀的后端必须返回
    // `Unsupported`；不能用一次列表查询模拟原子空目录前置条件。
    //
    // # 错误与移除提交证据
    //
    // 失败通过 [`RemoveFailure`] 返回。locator 无效、目标不存在、对象不是
    // 目录、目录非空、根或挂载点不可删除、权限不足、只读文件系统、父条目
    // 或内容退役冲突、身份变化、backend 不支持，以及其它提交前失败使用
    // [`crate::RemoveTargetEvidence::NotRemovedByOperation`]。
    //
    // 原生空目录删除已经明确成功，随后发生协调收尾或结果交付失败时使用
    // [`crate::RemoveTargetEvidence::RemovedByOperation`]。远端提交已发送但
    // 确实无法证明结果时使用 [`crate::RemoveTargetEvidence::Unknown`]。
    // 任一证据都只描述本次单目录操作的 namespace 绑定提交事实，不表示同一
    // locator 当前仍为空，也不证明底层目录对象已经物理回收。
    //
    // 本方法不得为了删除成功而递归移除子项、修改 ACL 或只读属性、跟随最终
    // 链接、删除身份变化后的新对象，或者把目录非空降级成可忽略警告。所有
    // 可报告条件必须结构化返回，不得 panic。
    //
    // # 取消、重试与持久性
    //
    // 从未轮询的 Future 不得打开目录、登记许可或提交删除。原生删除尚未
    // 提交时取消必须释放已取得许可且不产生目录移除副作用。系统调用或远端
    // 请求一旦提交，Future Drop 只表示调用方停止等待；拥有型完成者必须继续
    // 到安全停止点，关闭内部句柄并撤销或完成许可，不能访问失效借用。
    //
    // 取消没有 [`RemoveFailure`] 返回通道，因此目标可能仍存在、已经移除或
    // 结果未知。严格空目录删除不是状态或响应幂等操作：一次成功后重试通常
    // 返回不存在，未知结果下盲目重试还可能删除后来在相同位置创建的新空
    // 目录。调用方必须重新查询并在需要时核验对象身份。
    //
    // 成功只表示名称绑定已移除或 backend 已不可撤销地接受该动作，不隐式
    // 刷新物理父目录、卷或远端目录索引，也不保证掉电、操作系统崩溃、失信
    // 硬件缓存或硬件损坏后的持久性。其它已打开目录句柄或平台内部引用可以
    // 延长底层对象存续，但不能把已成功的名称移除改写为失败。
    //
    // # 副作用与性能
    //
    // 本方法会修改 namespace，并可能打开父目录和目标目录探测句柄、查询
    // 稳定身份、更新进程内协调状态、执行系统调用或远端请求、分配临时状态
    // 并记录日志或指标，因此不是纯函数。它不调用用户回调，不扫描或删除
    // 目录内容，也不发送合成监听事件。
    //
    // 本地通常承担 `O(P)` 路径解析、常数次期望 `O(1)` 的分片协调核心准入、
    // 一次稳定目录身份核验和一次空目录删除系统调用；`P` 是路径长度或组件
    // 数。它不以目录项目数为复杂度变量，也不得为了判断为空执行 `O(N)`
    // 枚举。可能阻塞的打开、身份和删除工作必须由有界阻塞设施承载，不能
    // 长期占用调用方执行器 poll 线程。
    /// 在当前进程的受管操作范围内排它移除一个空目录。
    ///
    /// 本方法只删除一个目录，绝不递归。目录不存在、不是目录、提交时非空，
    /// 或同一目录项存在冲突操作时失败且不等待。成功不保证物理存储已经回收
    /// 或名称变更已经持久化；[`RemoveFailure`] 报告可证明的提交结果。
    fn remove_dir<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), RemoveFailure>>
           + Send
           + 'a;

    // 按 backend 原生语义移除空目录，不进入本库的目录条目协调器。
    //
    // # 作用与安全边界
    //
    // 本方法是 [`Self::remove_dir`] 的显式非协调版本。它仍是安全 Rust API：
    // adapter 必须保证所有成功和失败路径都维持 Rust 内存安全、原生句柄唯一
    // 所有权和底层文件系统有效状态；调用方不需要承担裸指针或 `unsafe`
    // 前置条件。
    //
    // `uncoordinated` 只表示本方法不取得进程内父条目许可、不登记目标目录
    // 内容退役许可，也不按稳定目录身份与其它受管 namespace 操作排序。它不
    // 放宽空目录条件、对象类型检查或错误证据合同，更不表示递归删除。本
    // crate 不提供 `remove_dir_all`；本方法永远不能删除任何子项。
    //
    // # 参数、返回值与运行时
    //
    // `locator` 在 Future 的 `'a` 生命周期内共享借用，不被消费。成功只返回
    // `()`；失败使用 [`RemoveFailure`]。Future 为 `Send + 'a`，可以在
    // namespace 与 locator 的借用期内跨线程迁移，不绑定具体异步运行时。
    // adapter 需要把同步目录删除或远端请求放入有界阻塞设施时，可以显式
    // 克隆拥有型 locator，但不能把该副本当成稳定目录身份。
    //
    // # 严格空目录与对象类型
    //
    // 本方法必须直接使用 backend 的原生“仅删除空目录”原语。目标不存在、
    // 不是目录或提交时非空均必须失败；不能先枚举再删除，不能在非空错误后
    // 递归清理，也不能把文件删除原语作为回退。
    //
    // 最终分量是符号链接、悬空符号链接、Windows 重解析点或其它非目录对象
    // 时不得跟随或删除，必须返回准确类型或不支持错误。中间分量仍按平台
    // 正常规则解析，本方法不是路径沙箱。namespace 根、挂载点、卷根和其它
    // 平台保留目录可以返回忙、权限或无效操作错误。
    //
    // # 与文件访问、流和监听的关系
    //
    // 本方法不查询文件稳定身份注册表，也不与任何 [`Self::File`]、读取、
    // 追加、刷新、截断、覆盖、文件 MMAP 或透明映射句柄冲突。可见子文件仍
    // 存在时，原生空目录条件会使删除失败；子文件名称已经移除后，其仍存活
    // 的拥有型文件句柄或映射不再是该目录的 namespace 子项。
    //
    // [`Self::DirectoryStream`]、[`Self::WalkStream`] 和以后声明的 watcher
    // 同样不阻止本方法。它们可以观察删除、结束或返回后端错误；已经交付的
    // 拥有型流项目必须继续内存安全。平台因目录枚举或监听原生句柄的共享
    // 模式拒绝删除时，本方法返回真实占用错误，不能强制关闭调用方资源。
    //
    // # 并发、身份与检查使用时间差
    //
    // 本方法不与同进程中的创建、改名、替换、其它删除或子项变更自动互斥。
    // 并发调用由底层空目录删除原语决定线性化结果：子项先建立时删除应以
    // 非空失败；目录先删除时子项操作应处理父目录消失。方法不等待任何本库
    // 资源或许可，但底层系统调用、阻塞设施调度和远端响应仍可能耗时。
    //
    // 因为没有父条目许可和稳定目录身份复核，本方法删除的是底层提交瞬间由
    // locator 解析到的空目录绑定，而不保证它仍是调用开始时观察到的对象。
    // 同一位置被并发替换为另一个空目录时，原生调用可能删除替换后的目录；
    // 这是选择本方法的明确弱语义。它仍不得跟随最终符号链接或删除非目录，
    // 也不得让路径竞态造成内存不安全。
    //
    // 本方法不会创建或读取跨进程 sidecar，不取得 `fs4` 锁，也不承诺协调
    // 不同进程、另一份库副本或库外原生调用。调用方如果需要当前进程受管
    // 操作间的确定顺序，必须使用 [`Self::remove_dir`]。
    //
    // # 远端能力边界
    //
    // 非协调不等于允许用“先列举、再无条件删除”的远端模拟。远端 adapter
    // 仍须具有真实目录对象和提交时为空的原子前置条件。纯对象前缀、无法
    // 区分目录与字符串前缀或只能提供最终一致列表的 backend 必须返回
    // `Unsupported`，不能因本方法较弱就删除未知子对象。
    //
    // # 错误与移除证据
    //
    // locator 无效、目标不存在、对象不是目录、目录非空、权限不足、只读
    // 文件系统、平台占用、路径竞态、backend 不支持和其它提交前失败使用
    // [`crate::RemoveTargetEvidence::NotRemovedByOperation`]。
    //
    // 原生删除已经明确成功，随后发生结果交付或内部资源收尾失败时使用
    // [`crate::RemoveTargetEvidence::RemovedByOperation`]；远端提交响应丢失
    // 或底层确实不能证明结果时使用
    // [`crate::RemoveTargetEvidence::Unknown`]。证据只描述本次名称绑定移除
    // 是否提交，不证明 locator 当前为空或目录字节已经物理回收。
    //
    // 实现不得重建目标、补偿删除其它对象、修改权限或 ACL、递归清理子项，
    // 也不得把非空和类型错误吞掉。所有可报告条件必须结构化返回，不得 panic。
    //
    // # 取消、幂等性、持久性与成本
    //
    // 从未轮询的 Future 不得提交删除。原生调用或远端请求提交后，Future
    // Drop 只表示调用方停止等待；拥有型完成者必须安全收尾，不能访问失效
    // 借用。取消没有错误证据通道，调用方必须按目标可能仍存在、已经删除或
    // 结果未知处理。
    //
    // 本方法采用严格存在语义，不具备状态或响应幂等性。成功后直接重试通常
    // 返回不存在；未知结果下盲目重试可能删除随后在相同 locator 建立的另一
    // 个空目录。成功也不隐式刷新父目录、卷或远端索引，不保证掉电、操作
    // 系统崩溃、失信硬件缓存或硬件损坏后的持久性。
    //
    // 本方法会修改 namespace，并可能执行路径解析、一次原生空目录删除或
    // 远端请求、分配临时状态并记录日志或指标，因此不是纯函数。本地通常为
    // `O(P)` 路径解析和一次删除系统调用；`P` 是路径长度或组件数。它不枚举
    // 目录，不查询稳定身份注册表，也不承担进程内协调器准入成本。
    /// 按底层平台或后端的原生语义移除一个空目录。
    ///
    /// 本方法只删除一个目录，绝不递归，也不与本库内其它目录项操作建立排它
    /// 顺序。目录不存在、不是目录或提交时非空均失败。该接口始终维持 Rust
    /// 内存安全；成功不保证物理回收或持久化。
    fn remove_dir_uncoordinated<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), RemoveFailure>>
           + Send
           + 'a;

    // 在同一原子改名域内严格地改名一个现有 namespace 条目，且绝不替换目标。
    //
    // # 作用、接口层级与非目标
    //
    // 本方法是 namespace 层的基础 `source -> destination` 改名入口。成功把
    // source 的名称绑定原子迁移到 destination：其它观察者不能看到“两个
    // 名称都不存在”的中间提交状态，也不能看到只完成解绑或只完成新绑定的
    // 半次成功。成功值只返回 `()`；失败通过 [`RenameFailure`] 同时携带统一
    // 诊断和本次原子提交证据。
    //
    // 本方法采用严格不替换语义。destination 只要在底层提交点已经存在任何
    // 文件、目录、符号链接、悬空链接或其它 namespace 对象，就必须失败，
    // 不能覆盖、删除、交换或合并目标。它不提供 `replace`、交换两个名称、
    // 跨 backend 搬运、跨文件系统复制后删除、目录树复制、内容重写或临时
    // 文件发布语义；本 crate 当前也不提供独立 `replace` API。
    //
    // source 与 destination 必须属于同一个 backend 实例和同一个原子改名
    // 域。本地通常要求相同挂载文件系统或 Windows 卷；远端要求 backend
    // 明确提供单次、严格不替换且原子可判定的名称变更。跨域请求必须在 source
    // 仍保持原绑定时返回 `Unsupported`、跨设备或等价错误，绝不能偷偷降级为
    // copy-and-delete，因为后者具有两个提交点、部分进度和完全不同的恢复模型。
    //
    // # 参数顺序、借用与异步运行时
    //
    // 参数顺序固定为“源定位符、目标定位符”。两个定位符都在返回 Future 的
    // 同一个 `'a` 生命周期内共享借用，不被消费；成功后调用方仍拥有原值，
    // 但 source 通常已经失效，destination 则可能在返回后立即被其它参与者
    // 再次改名或删除。定位符只是位置表示，不能作为成功后的稳定身份令牌。
    //
    // 返回 Future 为 `Send + 'a`，可以在 namespace 和两个定位符的借用期内
    // 跨工作线程迁移，不绑定 Tokio、async-std、smol、Monoio 或其它运行时。
    // adapter 只有在阻塞任务或取消后的拥有型完成者必须脱离调用栈时，才可
    // 克隆拥有型 locator；该克隆不能替代提交前的真实父目录和条目核验。
    //
    // source 与 destination 表示完全相同的目录项，或者已经解析为同一个
    // 现有绑定时，本方法严格失败，不把调用改写为幂等成功。该规则也覆盖
    // 大小写不敏感文件系统上的纯大小写改名，以及 destination 是 source 的
    // 另一条硬链接的情况。首批 API 不为这些平台特例增加隐式模式。
    //
    // # 支持的对象与最终符号链接
    //
    // source 可以是普通文件、空或非空目录，以及 adapter 能可靠识别并按
    // 名称操作的最终符号链接。最终分量是符号链接时改名链接自身，不跟随并
    // 改名其目标；悬空链接也属于可以改名的现有条目。中间分量仍服从平台的
    // 正常路径解析规则，本方法不是路径沙箱。
    //
    // Windows junction、挂载点和其它重解析点只有在 adapter 能证明底层原语
    // 改动的是预期链接对象，并能维持本合同的类型与身份语义时才可支持；未知
    // 重解析类型必须在提交前返回 `Unsupported`。设备、命名管道、套接字和
    // 特殊远端条目同样只能在 backend 明确证明原子改名能力时进入支持域。
    //
    // 目录改名把目录绑定及其整棵可见后代作为一个 namespace 子树迁移，不
    // 遍历、复制或逐项改名后代。source 目录不得移动到自身或任意后代位置；
    // adapter 必须在提交前拒绝该循环。方法不计算后代数量，不产生部分进度
    // 列表，也不借此提供本 crate 明确不存在的 `remove_dir_all` 能力。
    //
    // # 默认并发语义：不锁文件内容或既有句柄
    //
    // 本方法不查询或等待普通 [`Self::File`] 的内容操作计数，不取得读取、
    // 顺序读取、严格追加、覆盖、截断、刷新、MMAP 范围或映射生命周期租约。
    // 因而当前进程中正在读取、追加、刷新、创建映射或访问既有只读/可写映射，
    // 都不会仅因该事实被本库主动判为 `rename` 冲突；新的文件打开也可以与
    // 改名竞争，并按它真实解析 source 或 destination 的时刻取得相应对象。
    //
    // 对句柄绑定且被平台允许改名的本地文件，改名成功后，既有文件句柄、
    // `O_APPEND` 打开状态和映射仍然引用原文件对象，而不会按旧 locator 重新
    // 绑定到后来创建的新对象。已有追加继续写入被改名文件的当前尾部；已有
    // 映射继续映射同一对象。`rename` 本身不得修改文件内容、长度、映射权限
    // 或逻辑映射范围，也不隐式刷新映射脏页。
    //
    // 上述合同不是“所有平台都必须让改名成功”。Windows 文件映射对象通常
    // 会使改名因共享冲突失败；Windows 目录改名还可能因任意深度后代仍有
    // 打开文件而失败。其它文件系统、网络共享和远端 backend 也可以施加自己
    // 的占用限制。adapter 必须直接返回准确的平台占用、共享、权限或不支持
    // 错误，并使用 [`crate::RenameCommitEvidence::NotRenamedByOperation`]；
    // 不能为兑现抽象上的并发许可而关闭调用方句柄、解除映射、重试到成功或
    // 把系统拒绝伪装成成功。
    //
    // 同样地，本库不主动扫描目录后代来预测 Windows 是否允许目录改名。
    // Linux 等允许改名的系统可以成功并让后代既有句柄继续工作；Windows 等
    // 原生拒绝时直接失败。公开合同保证两种结果都保持 Rust 内存安全和明确
    // 提交证据，不承诺不同操作系统对占用状态给出相同成功率。
    //
    // # 源、目标目录项的短期非阻塞排它许可
    //
    // “不锁内容”不表示允许本 crate 自己的两个 namespace 写操作在检查与
    // 提交之间互相穿透。默认安全的创建、删除和改名会读取对象类型或稳定
    // 身份，再按目录项提交变更；如果另一个受管操作能在两步之间替换同一
    // 名称，就可能把已经核验的对象和最终修改的对象混为一谈。
    //
    // 内置 adapter 因此只对有交集的目录项使用短期、非阻塞、拥有型排它
    // 许可：
    //
    // 1. 解析并锚定 source 与 destination 的物理父 namespace；
    // 2. 以“父目录稳定身份、最终名称”的确定全序排列两个条目键并去重；
    // 3. 按该全序非阻塞取得全部条目许可，任一许可冲突便在副作用前失败；
    // 4. 不跟随最终符号链接地核验 source、destination 和原子改名域；
    // 5. 若 source 是目录，登记只覆盖该目录直接子项 namespace 变化的短期
    //    搬迁许可，不扫描或锁住更深后代；
    // 6. 重新核验父目录、条目、对象种类和必要身份后调用单次原子改名原语；
    // 7. 完成或安全失败后按相反顺序释放全部许可。
    //
    // 条目许可只与使用相同协调器并涉及相同 source/destination 名称的创建、
    // 删除、其它改名及以后可能加入的替换操作互斥。目录搬迁许可只与当前
    // 进程中对该目录直接子项进行的受管 namespace 变更互斥。完全无关的
    // 目录项可以并行；读取、追加、刷新、文件 MMAP、目录流、递归遍历和以后
    // 的 watcher 都不取得这些许可，也不会因它们而被本方法等待或取消。
    //
    // 所有冲突都立即返回，不排队等待另一操作结束。实现持有的是可以跨异步
    // 阶段移动的拥有型许可，不是跨 `.await` 保留的同步 mutex guard。同步
    // 临界区只允许查表、比较、计数和许可转移；其中禁止文件 I/O、`.await`、
    // 用户回调、可能阻塞的日志和无界分配。禁止反向取锁、原地升级或在取得
    // 后序许可后回头请求更小的键。
    //
    // 库外原生调用、另一进程或未共享同一静态注册表的库副本不会自动服从
    // 这些进程内许可。底层严格原子改名仍必须独立处理这些参与者；进程内
    // 门禁不能被用来替代原生不替换条件，也不能被描述成跨进程事务。
    //
    // # 原子不替换、竞态与线性化点
    //
    // adapter 必须让“destination 不存在”的条件与名称迁移在同一个底层原子
    // 操作中判定。本地 Linux 支持域应使用 `renameat2(RENAME_NOREPLACE)` 或
    // 语义等价原语；Windows 应使用 `ReplaceIfExists = FALSE` 的句柄级改名
    // 信息类或经过证明的等价原语。不能先调用 [`Self::try_exists`]、metadata
    // 或目录枚举，再调用会覆盖 destination 的普通 rename。
    //
    // 线性化点是底层原子原语提交 source 解绑与 destination 绑定的瞬间。
    // 不合作参与者在此前创建 destination 时，本次操作必须失败且 source
    // 保持绑定；本次先提交时，竞争者应观察 source 消失或 destination 已经
    // 存在。平台只能提供覆盖式改名、检查后改名或 copy-and-delete 时，adapter
    // 必须返回 `Unsupported`，不能以较弱实现冒充本合同。
    //
    // 进程内许可之外的路径祖先仍可能被不合作参与者改名、替换或重新挂载。
    // 本地实现应尽量使用稳定父目录句柄和相对改名原语缩小检查后使用窗口；
    // 无法为当前 locator 模型排除错误目标的 backend 必须收窄支持域。本接口
    // 不是抵御恶意目录树修改的通用沙箱。
    //
    // # 文件身份、定位符迁移与现有资源
    //
    // 改名成功不开始新的文件内容生命周期。本库的逻辑文件实例和目标代次
    // 应继续表示同一底层对象；source 位置绑定失效，destination 成为新位置。
    // 已经打开的 [`Self::File`] 和映射句柄必须继续依赖其拥有的底层句柄与
    // 协调核心，不能在后续 I/O 时按缓存的旧 source locator 偷偷重新打开。
    // 旧 locator 若随后创建了新对象，新打开必须取得新对象自己的身份和核心。
    //
    // Linux 常规文件系统的设备号与 inode、Windows NTFS 的文件 ID 通常可在
    // 同域改名后继续汇合；但底层身份能力不是跨文件系统常量。例如 FAT 改成
    // 更长名称时文件 ID 可以变化，ReFS 又要求完整 128 位 ID。若 adapter
    // 依赖的身份值可能因本次改名变化，它只能在能安全迁移身份别名、且不会
    // 让并发新打开形成第二个协调核心时支持；否则必须在提交前返回
    // `Unsupported`。不能在改名后才发现已经无法维持 MMAP、追加或删除协调。
    //
    // 目录改名同样不扫描并逐项迁移全部后代资源。支持的本地文件系统必须让
    // 后代已打开句柄按自身稳定对象继续工作；后代原 locator 只成为过期位置
    // 信息。依赖路径重开的 adapter、用 locator 充当身份的远端实现，或只能
    // 以复制后删除模拟目录移动的 backend，均不得实现该能力。
    //
    // # 普通协调域与跨进程协议
    //
    // 本方法不建立跨进程 sidecar、`fs4` 锁或安全 authority，也不承诺协调
    // 其它进程。当前进程中已经检测到 source 或 destination 进入
    // [`Self::CrossProcessAuthority`] 协调域时，默认安全 adapter 必须在提交
    // 前返回冲突；不能让普通改名把持久协议记录、授权中的受管 locator 和
    // 实际文件对象拆开。
    //
    // 另一进程持有 authority 而当前进程无法从既有协议可靠检测时，调用方仍
    // 受建立 authority 时的 `unsafe` 合作承诺约束：所有参与者必须通过同一
    // 协议执行 namespace 变更。绕过该承诺调用普通 `rename` 会使旧授权、
    // sidecar 和路径身份失配，本方法不能因此被描述成跨进程安全改名。首批
    // API 不提供跨进程协调式 rename；需要该能力时必须另行设计持久状态机、
    // 双父目录锁序、崩溃恢复和授权迁移，不能在本方法内部静默猜测。
    //
    // # 错误与提交证据
    //
    // 失败统一返回 [`RenameFailure`]。参数无效、source 不存在、destination
    // 已存在、对象或重解析类型不支持、同一条目、目录自包含、跨 backend 或
    // 跨原子域、进程内条目许可冲突、当前跨进程协调域冲突、身份能力不足、
    // 权限或平台共享拒绝，以及底层明确在提交前失败时，必须使用
    // [`crate::RenameCommitEvidence::NotRenamedByOperation`]。
    //
    // 底层名称迁移已经明确成功，但后续结果转换、取消后的交付或内部状态收尾
    // 发生可报告失败时，使用
    // [`crate::RenameCommitEvidence::RenamedByOperation`]。远端请求已经提交、
    // 响应丢失且 backend 确实不能证明结果时才使用
    // [`crate::RenameCommitEvidence::Unknown`]；本地系统调用明确返回成功或
    // 失败时不得用 `Unknown` 掩盖可知事实。
    //
    // 任一证据都只描述本次调用是否跨过原子改名提交点，不是 source 或
    // destination 的实时快照。其它参与者可以在提交后立即继续改名或删除；
    // 调用方在 `Unknown` 后必须重新查询两个位置并核验身份，不能盲目重试。
    // 所有可报告条件必须结构化返回，不得 panic；实现不得为了制造整洁失败
    // 外观而反向改名、删除竞争者目标或重新创建 source。
    //
    // # 取消、幂等性、持久性与副作用
    //
    // 从未轮询的 Future 不得取得条目许可、打开父目录或提交改名。原生系统
    // 调用、阻塞任务或远端请求一旦提交，Future Drop 只表示调用方停止等待；
    // 拥有型完成者必须继续到安全停止点，保存真实提交证据并释放全部许可，
    // 不能访问已经结束的 locator 借用。取消没有错误返回通道，调用方必须把
    // 结果视为可能成功并重新查询。
    //
    // 本方法不是状态或响应幂等操作。一次成功后的同参数重试通常得到 source
    // 不存在或 destination 已存在；未知结果下盲目重试还可能与后来创建的
    // source 或 destination 竞争。调用方不能把严格不替换误解为自动可重试。
    //
    // 成功只证明 namespace 原子改名已经提交，不隐式执行文件 `flush`、MMAP
    // 刷新、父目录同步、卷刷新、远端索引持久化或跨文件事务。它不保证掉电、
    // 操作系统崩溃、失信硬件缓存或硬件损坏后的名称持久性。需要持久发布
    // 证据时必须使用以后单独冻结的平台能力，不能从 `Ok(())` 推导出来。
    //
    // 本方法会修改 namespace，并可能打开父目录和 source 探测句柄、查询
    // 稳定身份、更新进程内条目许可、执行系统调用或远端请求、分配临时状态
    // 及记录日志或指标，因此不是纯函数。它不调用用户代码，不扫描目录树，
    // 也不发送伪造的 watcher 事件；监听者只观察 backend 实际产生的变化。
    //
    // 本地通常承担 `O(Ps + Pd)` 的父路径解析、常数次条目许可准入、必要的
    // 稳定身份核验和一次原子改名系统调用；`Ps`、`Pd` 分别是两个路径长度或
    // 组件数。目录改名成本不得随后代数量线性增长，但 Windows 原生实现可以
    // 为检测后代打开状态承担系统内部成本。可能阻塞的系统调用必须由有界
    // 阻塞设施承载，不能长期占用异步执行器 poll 线程。
    //
    // # 参考基线与采纳差异
    //
    // 本合同于 2026-08-31 核验了 Linux man-pages 6.18 的
    // [`rename(2)`](https://man7.org/linux/man-pages/man2/rename.2.html)、
    // [`open(2)`](https://man7.org/linux/man-pages/man2/open.2.html) 与
    // [`mmap(2)`](https://man7.org/linux/man-pages/man2/mmap.2.html)，Microsoft
    // 的
    // [`CreateFileW`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew)、
    // [`FileRenameInformation`](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fsa/87f86c9b-6c2a-4803-84b7-131a74a434fa)、
    // [目录后代打开检测算法](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fsa/133840e4-778e-44ca-9b41-da2323615075)、
    // [`BY_HANDLE_FILE_INFORMATION`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information)
    // 以及 Windows 团队对
    // [`CreateFileMapping` 改名限制](https://devblogs.microsoft.com/oldnewthing/20160810-00/?p=94055)
    // 的说明。
    //
    // 本方法采纳“改名改变名称绑定而非既有句柄对象”和平台原子提交边界，
    // 但刻意拒绝传统覆盖式 rename、检查后覆盖、跨域 copy-and-delete 以及
    // 对平台占用差异作虚假统一。依赖、操作系统或文件系统能力变化时，adapter
    // 必须重新核验这些来源及自身原子不替换、身份和打开句柄行为。
    /// 在同一原子改名域内严格改名，且绝不替换目标。
    ///
    /// `source` 必须存在，`destination` 必须不存在；跨文件系统、跨容器或其它
    /// 无法原子提交的组合失败。本方法不复制后删除，也不覆盖目标。默认改名
    /// 不与已经打开的内容 I/O 或映射建立排它关系；平台若因占用状态拒绝，
    /// 直接返回错误。失败通过 [`RenameFailure`] 报告提交点证据；取消后结果
    /// 可能需要重新查询，成功不隐含持久化屏障。
    fn rename<'a>(
        &'a self,
        source: &'a Self::Locator,
        destination: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), RenameFailure>>
           + Send
           + 'a;

    // 以唯一访问角色独立打开一个已经存在的普通文件或远端文件对象。
    //
    // 本方法是普通、仅进程内协调的文件资源获取入口。`locator` 先由当前
    // namespace 选择并解析到一个具体 backend，`access` 再决定该 backend
    // 必须申请的最小权限和返回资源唯一获准的 [`FileAccessMode`]。成功返回
    // 的 [`Self::File`] 拥有底层资源、稳定身份登记和必要配置，不借用本次
    // 调用参数。
    //
    // 本方法只打开已经存在的目标，不创建文件、目录或远端对象。后续文件
    // 创建必须使用独立入口，不能通过一个不断扩张的打开选项集合混入本方法。
    //
    // # 参数顺序、借用与角色
    //
    // 参数顺序固定为“目标位置、访问角色”。`locator` 只在 Future 生命周期
    // 内共享借用，避免调用方为了一次打开复制拥有型位置；`access` 按值进入
    // Future，并在成功资源的整个生命周期内保持不可变。一个资源只有一个
    // 角色，需要读取、严格追加、截断或映射等多种能力时，调用方必须分别
    // 调用本方法获得多个独立资源。
    //
    // 打开阶段必须验证后端原则上能够实现请求角色。完全不支持的角色应返回
    // [`pi_result::ErrorKind::Unsupported`]，权限不足应保留为权限错误；不能
    // 返回一个已知其核心操作必然失败的伪资源。成功打开仍不是以后每次操作
    // 必然成功的证明：权限、挂载、远端版本、协调状态和设备状态都可能变化。
    //
    // # 只打开既有目标
    //
    // 对标准本地 adapter，最终路径分量默认按平台普通打开规则跟随符号链接，
    // 并要求最终目标是受支持的普通文件。不存在、悬空链接、链接循环、目录、
    // 管道、设备或其它未纳入支持域的对象必须返回明确错误，不能伪装成空
    // 文件。路径中间分量仍按平台正常解析规则处理。
    //
    // 远端 adapter 必须按自己的存在性和文件对象合同核验目标。若底层打开
    // 只是惰性构造客户端对象，adapter 仍须在本 Future 成功前补足本接口要求
    // 的存在性与角色能力检查；不能让“目标不存在”无条件延迟到第一次 I/O。
    //
    // # 打开没有内容副作用
    //
    // 成功只取得以后申请操作的能力，不执行该操作：
    //
    // - [`FileAccessMode::Read`] 不读取数据，也不推进顺序逻辑游标；
    // - [`FileAccessMode::Append`] 建立独立的严格追加打开状态，但不写入字节；
    // - [`FileAccessMode::Overwrite`] 不覆盖、清空或截断已有内容；
    // - [`FileAccessMode::Truncate`] 不改变文件长度；
    // - [`FileAccessMode::ReadMmap`] 和
    //   [`FileAccessMode::ReadWriteMmap`] 不建立映射、冻结长度或占用范围。
    //
    // 打开时不得以 `truncate(true)` 实现 `Overwrite` 或 `Truncate` 角色。普通
    // 内容与长度副作用只能发生在相应 [`FileIo`] 方法已经取得操作租约之后。
    //
    // # 独立资源与重复打开
    //
    // 相同稳定文件身份的相同角色或不同角色都可以被独立打开任意次数；本
    // 接口不采用“同 Locator、同角色只能打开一次”的资源生命周期限制。
    // 空闲资源不持有读取、追加、覆盖、截断或映射操作租约，因此不能只因
    // 其潜在角色阻塞另一个资源的合法操作。
    //
    // 每次成功调用必须产生新的逻辑资源和新的底层打开状态。实现不得克隆
    // 已有公开资源，也不得使用 `dup`、`DuplicateHandle`、`File::try_clone`
    // 或等价方式复制一个既有打开状态来构造新的公开资源。本地严格追加角色
    // 尤其必须获得新的系统追加模式打开；远端资源也不得共享会破坏独立资源
    // 语义的可变游标或未隔离 writer 状态。
    //
    // [`Self::File`] 按 trait 合同不可公开克隆。即使调用方另行把资源放进
    // `Arc`，同一资源和不同独立资源的并发方法调用仍必须经过下述协调状态，
    // 不能把 `Send + Sync` 解释为底层句柄可以无协调地并发使用。
    //
    // # 稳定文件身份与进程级汇合
    //
    // `Self::Locator` 只是位置表示，不能作为互斥键。不同路径、符号链接和
    // 硬链接可能指向同一文件；相同路径也可能在相邻时刻指向不同文件。标准
    // 本地 adapter 必须先执行新的原生打开，再从已经打开的句柄取得稳定文件
    // 身份，并以该身份把资源汇合到进程级共享协调核心。这避免“先按路径检查、
    // 随后目标被替换”的检查与使用时间差竞态。
    //
    // Linux 支持域通常使用打开后元信息中的设备号与 inode；Windows 使用卷
    // 身份与文件 ID。具体平台表示属于私有实现，不能进入公共 locator、错误
    // 或序列化格式。远端 adapter 必须使用与 backend 实例绑定的稳定对象键；
    // 无法可靠汇合别名或版本的后端必须收窄能力，不能伪造安全保证。
    //
    // 所有内置本地 namespace 实例必须共享同一份进程级注册表。两个线程并发
    // 打开同一稳定身份时，只能在原子注册入口处得到同一个私有协调核心；
    // 不能因分别使用两个 namespace 对象而生成彼此不可见的状态。成功资源、
    // 映射句柄和取消后仍在途的完成所有者分别持有必要的引用；最后一个参与者
    // 释放后，注册表允许安全回收失效弱引用。
    //
    // 该进程内保证只覆盖共享这份协调注册表的库实例和受管 adapter。绕过本
    // 库的原生句柄、另一份未共享静态状态的库副本或不遵守 trait 合同的第三方
    // adapter 不会被普通打开自动观察；需要合作式跨进程保证时必须使用
    // [`Self::establish_cross_process_authority`] 和
    // [`Self::open_with_cross_process_authority`]。
    //
    // # 操作时互斥与映射范围
    //
    // 打开登记不能替代操作准入。每个 [`FileIo`] 方法必须在接触底层 I/O、
    // 脱离 buffer 或产生副作用之前，经资源保存的协调核心原子完成“检查当前
    // 状态并登记本次操作”。只读取一个标志再执行 I/O 会留下两个线程同时
    // 通过检查的竞态，不满足本合同。
    //
    // 映射创建必须同时检查待建立和已活动的全部逻辑范围。任意两个半开区间
    // `[a_start, a_end)` 与 `[b_start, b_end)` 在
    // `a_start < b_end && b_start < a_end` 时相交；只读或读写权限不同不构成
    // 例外。相邻的 `[0, n)` 与 `[n, m)` 不相交。并发申请必须先原子登记待
    // 建立范围，一个申请完成登记后，任何相交申请都必须立即返回明确冲突，
    // 不能等双方都完成原生建图后才发现冲突。
    //
    // 映射成功后，范围租约由返回的透明映射句柄持有，而不是由创建它的
    // [`Self::File`] 持有。只读句柄的克隆共享同一个映射和同一份范围租约；
    // 最后一个克隆释放后才撤销。可写句柄独占持有。因而原文件资源可以先行
    // Drop，而其它线程上的普通读取、覆盖、截断、普通强刷新、默认协调删除
    // 和以后可能加入的替换仍必须在活动映射释放前返回冲突。
    //
    // [`Self::rename`] 是刻意保留的平台原生例外：它不查询映射生命周期，也
    // 不因活动映射主动返回本库冲突。Linux 等系统可以完成改名并让映射继续
    // 指向同一对象；Windows 的文件映射通常会使底层改名以共享冲突失败。
    // adapter 必须保留该真实平台结果，不能把其中任一行为伪装成跨平台必然
    // 成功或必然由映射协调器拒绝。
    //
    // 已经建立的映射允许随后执行严格尾部追加；多个独立追加资源的完整公开
    // `append` 调用仍必须按稳定身份串行。正在执行或已经获准的追加与新映射
    // 创建短暂互斥，新映射遇到追加必须立即返回冲突。映射范围自身不能作为
    // 同一稳定文件身份追加或覆盖的输入 buffer；地址与文件身份检查属于独立
    // 的前置安全门禁。
    //
    // # 普通协调域与跨进程协调域
    //
    // 本方法只加入进程内协调域，不创建 sidecar 目录、协议文件或 `fs4` 文件
    // 锁。通过本方法打开的映射角色可以使用相应未协调 `unsafe` 建图入口，
    // 但调用安全协调式建图入口必须返回授权缺失错误，不能自动升级或静默
    // 降级。
    //
    // 如果同一稳定身份已经存在跨进程 authority、其派生资源、映射或仍在途
    // 操作，本方法必须在返回资源前失败。反向地，活动普通资源会阻止该文件
    // 建立跨进程 authority。一个文件在同一进程中不能同时进入彼此不可见的
    // 普通协调域和跨进程协调域。
    //
    // # Backend 选择与句柄所有权
    //
    // backend 必须在打开时一次选定，后续方法不能依据操作种类把同一个公开
    // 文件在不同 I/O 库之间来回转换。标准本地 adapter 使用 `async-fs` 打开
    // 和拥有本地数据句柄；远端 adapter 只对经过能力核验的角色使用 Fusio
    // 或其它远端实现。组合 namespace 可以用私有枚举分派两类资源，单后端
    // namespace 应优先使用自己的具体关联类型。
    //
    // 本地映射设施可以在句柄拥有者存活期间借用原生 descriptor，但不能从
    // 同一个裸值再构造第二个拥有型文件对象。需要第二个公开资源时必须重新
    // 打开并重新核验稳定身份。跨进程 `fs4` 锁使用独立 sidecar 文件；目录
    // 遍历和文件监听使用各自拥有的路径级资源，均不得偷用或接管本数据句柄。
    //
    // # 错误、取消与资源清理
    //
    // 定位符无效、目标不存在、对象类型不支持、权限不足、角色不支持、稳定
    // 身份无法可靠取得、普通/跨进程协调域冲突、资源耗尽、远端协议错误和
    // 底层 I/O 失败均通过 [`pi_result::Error`] 返回。可报告条件不得 panic。
    //
    // 从未轮询的 Future 不得打开文件或登记资源。原生打开、身份查询或阻塞
    // 工作一旦提交，调用方丢弃 Future 只表示停止等待；内部拥有型完成所有者
    // 必须继续到安全停止点。若最终打开成功但调用方已经取消，它必须关闭新
    // 句柄、撤销候选资源登记并释放准入状态，不能留下无法取得的幽灵资源。
    //
    // 同步打开、稳定身份查询和可能阻塞的清理必须由 adapter 的阻塞设施承载，
    // 不能长期占用调用方执行器的 poll 线程。返回 Future 为 `Send + 'a`，可
    // 在 namespace 与 locator 的共享借用期内跨线程迁移；成功资源则拥有全部
    // 状态并满足 `'static`。
    //
    // # 热路径性能与锁纪律
    //
    // 打开和稳定身份登记属于冷路径，可以执行原生打开、身份系统调用、一次
    // 进程级注册表查询和必要分配。成功资源必须直接保存共享协调核心，后续
    // 普通 [`FileIo`] 热路径不得重新解析 locator、再次查询全局注册表、重新
    // 打开文件或重复取得稳定身份。
    //
    // 内置 adapter 的进程级注册表必须分片，不能让不同稳定文件身份的普通
    // 操作竞争一把全局锁。每文件同步只保护短暂且不执行 I/O 的状态转移；
    // 任何文件系统调用、远端请求、buffer 复制、等待队列休眠或 `.await` 都
    // 不能在该临界区内发生。跨异步等待的权利必须由拥有型操作租约承载。
    //
    // 普通非映射准入应只执行常数数量的每文件状态检查。由于所有待建立和
    // 活动映射逻辑范围始终两两不相交，内置 adapter 的范围索引应按起点有序，
    // 以 `O(log M)` 查询新范围的前驱和后继完成相交判断；`M` 是该稳定文件
    // 身份当前待建立与活动映射总数。不得在热路径上按资源打开总数或全部映射
    // 线性扫描，也不得为了避免短锁而用无法原子登记的无锁预检查冒充正确性。
    //
    // 原子摘要、内联单范围等优化可以在真实基准证明收益后加入，但只能作为
    // 保守快速拒绝或存储优化；最终获准状态仍必须在线性化点原子提交。第三方
    // adapter 若无法满足相近复杂度，应公开说明其性能边界，不能改变互斥和
    // 生命周期语义换取速度。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法不修改目标内容、长度或 namespace 条目，但会打开系统句柄或远端
    // 会话、更新进程内身份状态、引用计数、日志和指标，因此不是纯函数。
    // 重复调用可以安全地取得更多独立资源，但每次成功都产生新的打开状态，
    // 所以不是资源意义上的幂等操作。
    //
    // 本地通常至少需要一次原生打开、一次句柄身份查询和一次分片注册表准入；
    // 远端通常至少需要存在性或能力请求。接口不承诺零分配、零系统调用或固定
    // 延迟。资源 Drop 自动关闭其底层打开并撤销资源登记，但不隐式执行强文件
    // 刷新；需要持久化证据的调用方必须显式等待相应刷新方法成功。
    /// 以唯一 [`FileAccessMode`] 独立打开一个已经存在的文件资源。
    ///
    /// 本方法不创建、截断、映射或修改目标。成功资源拥有自身生命周期，且
    /// 只能调用所选访问模式允许的 [`FileIo`] 方法。多个资源操作同一文件时
    /// 必须分别打开；模式兼容只允许它们共存，不自动保证具体操作可并发。
    fn open<'a>(
        &'a self,
        locator: &'a Self::Locator,
        access: FileAccessMode,
    ) -> impl Future<Output = pi_result::Result<Self::File>> + Send + 'a;

    // 原子排他地创建一个空文件，并返回绑定到所选唯一访问角色的资源。
    //
    // # 作用、接口层级与非目标
    //
    // 本方法是 namespace 中“目标最终名称必须尚不存在”的基础文件创建入口。
    // 它把原子排他创建、打开后稳定身份核验、进程内协调汇合和首个文件资源
    // 交付组成一个异步操作。成功结果拥有全部资源，不借用 `locator` 或本次
    // 调用栈。
    //
    // 本方法只创建一个逻辑长度为零的普通文件或空远端对象。它不创建父目录、
    // 不写入初始内容、不复制其它文件、不覆盖或截断已有目标，也不建立跨进程
    // authority。父目录或远端等价容器必须已经存在。创建目录、递归创建、带
    // 初始内容的发布和跨进程协调式创建分别属于其它接口。
    //
    // # 参数顺序与访问角色
    //
    // `locator` 在前，描述新目标的最终 namespace 位置；`access` 在后，按值
    // 决定成功返回的 [`Self::File`] 在整个生命周期内唯一可以申请的操作角色。
    // 该顺序与 [`Self::open`] 一致。方法不保存对任一参数的借用。
    //
    // `access` 不改变创建副作用：
    //
    // - [`FileAccessMode::Overwrite`] 不在创建阶段调用覆盖写；
    // - [`FileAccessMode::Truncate`] 不执行截断；
    // - [`FileAccessMode::Append`] 不写入任何字节；
    // - 映射角色不建立空映射，且必须等文件以后具有非零可映射范围再建图。
    //
    // adapter 已知无法为新建空目标提供所选角色时，应在提交创建之前返回
    // `Unsupported`，不能先创建目标再把一个已知不可用的伪资源交给调用方。
    //
    // # 排他创建、符号链接与原子性
    //
    // 最终目标只要已经存在，本次调用就必须失败，不能打开、覆盖、清空或
    // 替换它。本地最终路径组件是普通符号链接或悬空符号链接时也视为已经
    // 存在；本方法不能沿该链接创建或打开其指向目标。父路径组件仍按 adapter
    // 公开的平台解析规则处理，本 crate 不因此成为路径沙箱。
    //
    // 本地 adapter 必须使用 `create_new` 对应的单次平台排他创建原语，例如
    // Unix 的 `O_CREAT | O_EXCL` 或 Windows 的 `CREATE_NEW`，不能先调用
    // [`Self::try_exists`] 再创建。远端 adapter 必须使用后端条件创建或等价的
    // 原子“不存在”前置条件。无法保证这一点的 adapter 必须在产生目标副作用
    // 前返回 `Unsupported`，不能用客户端检查模拟原子性。
    //
    // 该保证只覆盖 namespace 中同一个最终目标名称的排他创建结果，不承诺
    // 整个父目录快照、路径解析期间的所有祖先对象或不合作远端网关保持不变。
    //
    // # 稳定文件身份与进程内协调
    //
    // 本地原生创建成功后，adapter 必须从已打开句柄取得稳定文件身份，再与
    // [`Self::open`] 使用的同一份进程级分片注册表汇合。不能关闭首个句柄后
    // 仅凭路径重新打开并假定仍是刚创建的文件，也不能用 locator 本身充当
    // 协调键。
    //
    // 原生创建与登记之间，另一个线程可能已经打开刚出现的文件。两个路径
    // 都必须按稳定身份原子取得同一个协调核心，而不能形成彼此不可见的状态。
    // 成功资源直接保存该共享核心，后续 [`FileIo`] 热路径不重复查询全局表。
    //
    // 本方法只加入普通进程内协调域，不创建 sidecar 目录、协议文件或 `fs4`
    // 文件锁，也不返回 [`Self::CrossProcessAuthority`]。需要从创建提交点开始
    // 建立合作式跨进程协议时，不能先调用本方法再调用
    // [`Self::establish_cross_process_authority`]；二者之间存在不受协议保护的
    // 窗口，必须使用以后单独冻结的协调式创建入口。
    //
    // # 成功、持久性与默认创建属性
    //
    // 成功只证明空目标已经建立、稳定身份与协调状态已经核验，并且首个资源
    // 已交付。它不证明目录项、空内容、时间或其它元信息已经到达持久介质，
    // 也不隐式刷新文件或父目录。需要持久性证据的调用方必须使用后续明确
    // 支持相应保证的刷新或发布接口。
    //
    // 本方法采用 adapter 的默认创建权限、安全描述和远端对象属性。它不接受
    // Unix mode、Windows ACL、远端 IAM、对象标签或 backend 扩展选项。需要
    // 原子指定这些安全属性的调用方不能采用“创建后再修改”并假定中间窗口
    // 安全；相关接口必须在可移植语义和平台原语完成独立调研后另行冻结。
    //
    // # 普通错误与目标副作用证据
    //
    // Future 的普通错误值始终是 [`CreateFailure`]，调用方必须同时处理其中的
    // [`pi_result::Error`] 和 [`crate::CreateTargetEvidence`]：
    //
    // - 参数、locator、父目录、访问角色、协调域或能力检查在创建提交前失败，
    //   以及平台明确报告目标已存在时，必须使用
    //   [`crate::CreateTargetEvidence::NotCreatedByOperation`]；
    // - 原生创建已经成功，随后稳定身份查询、进程内协调登记或资源交付失败
    //   时，必须使用 [`crate::CreateTargetEvidence::CreatedByOperation`]；
    // - 远端提交响应丢失或 backend 无法证明创建结果时，必须使用
    //   [`crate::CreateTargetEvidence::Unknown`]。
    //
    // `CreatedByOperation` 不意味着错误返回时目标仍位于同一 locator，也不
    // 证明它未被外部修改。adapter 不得为了把证据改写成“未创建”而自动删除
    // 已建立目标；其它参与者可能已经观察、打开、改名或使用它，补偿删除会
    // 引入更危险的竞态。
    //
    // 可报告条件不得 panic。目标已存在、父目录不存在、权限不足、locator
    // 无效、角色或原子创建不受支持、普通/跨进程协调域冲突、身份查询失败、
    // 资源耗尽和底层 I/O 或远端协议失败都必须进入结构化失败结果。
    //
    // # 取消与资源生命周期
    //
    // 从未轮询的 Future 不得创建目标或登记资源。原生创建一旦提交，调用方
    // 丢弃 Future 只表示停止等待；内部拥有型完成所有者必须继续到安全停止点，
    // 关闭未交付句柄并撤销候选资源登记。它不得因取消而自动删除已经建立的
    // 目标。
    //
    // 取消没有返回 [`CreateFailure`] 的通道，因此调用方在不确定完成点取消后
    // 必须按“目标可能已经创建”处理，并在需要时重新查询与核验。后台清理只
    // 防止句柄和协调租约泄漏，不提供回滚或事务语义。
    //
    // # 并发、线程和运行时
    //
    // 返回 Future 为 `Send + 'a`，可在 `self` 与 `locator` 的共享借用期内跨
    // 线程迁移。同步创建、身份查询和可能阻塞的清理必须由 adapter 的阻塞
    // 设施承载，不能长期阻塞调用方执行器的 poll 线程。
    //
    // 同一进程内，本方法必须在底层创建前非阻塞地取得“物理父 namespace、
    // 最终名称”对应的拥有型排它许可；同名创建、`copy_new` 目标预留、安全
    // 删除、改名或其它 namespace 写操作已经持有许可时，本次调用在副作用前
    // 返回冲突。不同名称使用不同许可，不由一把进程级路径锁串行化。
    //
    // 该许可不能替代底层 `create_new` 原语。不合作进程、远端参与者或库外
    // 调用仍由底层排他条件决定唯一成功者。成功后的内容操作必须经稳定身份
    // 协调器完成操作准入；旁路本库的原生句柄和不合作进程不受普通进程内
    // 协调合同约束。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法会创建 namespace 条目或远端对象、打开底层资源、查询稳定身份并
    // 更新进程内注册状态，因此不是纯函数。一次成功后用同一 locator 重试
    // 通常得到 `AlreadyExists`；它既不具备状态幂等性，也不具备响应幂等性，
    // 未知完成结果不能直接重试。
    //
    // 本地成本通常为 `O(P)` 路径解析、一次排他创建系统调用、一次句柄身份
    // 查询和一次期望 `O(1)` 的分片注册表汇合；`P` 是路径长度或组件数。远端
    // 通常至少产生一次条件创建请求。该操作属于资源获取冷路径；成功资源的
    // 后续普通 I/O 不承担这些重复成本。
    /// 原子排他创建一个空文件，并以指定访问模式返回资源。
    ///
    /// 最终位置存在任何对象时失败，且不会覆盖、截断或复用它。成功结果拥有
    /// 文件资源；失败通过 [`CreateFailure`] 报告本次调用是否已创建目标。
    /// 取消发生在提交点附近时，调用方必须把目标视为可能已经创建并重新查询。
    fn create_new<'a>(
        &'a self,
        locator: &'a Self::Locator,
        access: FileAccessMode,
    ) -> impl Future<
        Output = pi_result::RawResult<Self::File, CreateFailure>,
    > + Send + 'a;

    // 把一个稳定源文件的确定逻辑范围复制为严格不替换的新目标。
    //
    // # 作用、接口层级与非目标
    //
    // 本方法是 namespace 层的单文件复制与原子发布入口。它捕获 source 的
    // 一次逻辑长度 `L`，形成主内容精确等于该稳定源对象 `[0, L)` 的完整
    // destination，并保证最终名称只通过一次原子 `no-replace` 发布出现。
    // destination 在发布前不承载空或部分内容，发布成功时直接成为完整目标。
    //
    // 本方法不复制目录树、最终符号链接对象、硬链接关系、设备、管道、套接字
    // 或其它特殊对象；不覆盖、合并、追加或替换既有 destination；也不返回
    // 打开的 [`Self::File`]。需要随后访问新文件时，调用方必须在成功后另行
    // [`Self::open`]，并接受发布与再次打开之间的正常并发变化。
    //
    // # 参数顺序、借用与 Future
    //
    // 参数顺序固定为“源位置、目标位置”。`source` 与 `destination` 都只在
    // 返回 Future 的 `'a` 生命周期内共享借用，不被消费；成功或普通失败后，
    // 调用方仍拥有原定位符。但定位符只是位置表示，不是对象身份、提交令牌
    // 或结果快照，不能仅凭值相等判断底层对象关系。
    //
    // 返回 Future 为 `Send + 'a`，可以在 namespace 与两个定位符借用有效时
    // 跨工作线程迁移，不绑定 Tokio、async-std、smol、Monoio 或其它运行时。
    // Future 不承诺 `Sync`、`Unpin` 或 `'static`。需要 `'static` 顶层任务的
    // 调用方可以让 `async move` 拥有 namespace 和定位符，再在任务内部借用
    // 调用；adapter 不能通过扩大借用寿命伪造相同能力。
    //
    // 定位符克隆只允许发生在阻塞任务、远端请求或取消后完成者必须脱离调用
    // 栈的路径。内部完成状态必须拥有需要的 backend 客户端、句柄、定位信息
    // 和协调许可，不能在公开 Future 被丢弃后继续引用 `self` 或参数。
    //
    // # Source 对象、范围与最终符号链接
    //
    // 最终 source 分量按 adapter 的普通文件打开规则跟随符号链接；悬空链接、
    // 链接循环、目录和特殊对象均失败。成功打开后必须从拥有型句柄取得稳定
    // 文件身份，或者取得与 backend 实例绑定且能稳定读取的远端对象版本；
    // 后续传输绝不能按 source 路径重新打开并误读同名替代对象。
    //
    // adapter 只捕获一次源主内容逻辑长度 `L: u64`，并且只读取同一稳定对象
    // 的半开区间 `[0, L)`。空源合法，成功结果的逻辑长度为零。复制期间后来
    // 追加的字节不进入目标；外部把源缩短到 `L` 以下而造成意外文件尾时必须
    // 失败并禁止发布，不能用零填充或缩短成功目标掩盖异常。
    //
    // 本方法不承诺 `[0, L)` 来自单一时点的内容快照。当前进程中受管的覆盖、
    // 截断和映射会被下面的租约排除，但其它进程、库外句柄或不受管 backend
    // 仍可能修改源范围；在不破坏内存安全且没有稳定版本能力时，目标内容只
    // 能解释为传输实际观察到的数据。要求事务快照的调用方必须使用 backend
    // 版本、文件系统快照或以后独立设计的能力。
    //
    // # Destination 的严格不存在条件
    //
    // destination 的父目录或远端等价容器必须已经存在。最终分量在原子发布
    // 线性化点存在任何对象——普通文件、目录、符号链接、悬空符号链接、
    // Windows 重解析点或其它条目——都必须失败，且本次操作不得打开、覆盖、
    // 清空、删除或修改该对象。最终分量永远不通过跟随链接来选择另一个目标。
    //
    // source 与 destination 文本相同，或 destination 是 source 已存在的硬
    // 链接或别名时，同样因目标已经存在而失败；不能把这种请求改写为幂等
    // 成功。客户端 `try_exists` 后普通 rename/copy 不是合法实现，最终不存在
    // 检查必须与发布在一个 backend 或操作系统原子动作中完成。
    //
    // # 目标条目排它预留
    //
    // 在创建暂存物和读取 source 之前，内置 adapter 必须按“backend 身份、
    // 物理父 namespace 稳定身份、backend 原生最终名称等价键”登记 destination
    // 的进程内条目排它预留。Windows 键必须服从具体目录的真实大小写敏感
    // 设置，远端键必须服从对象存储规则；未经解释的 locator 文本不能直接
    // 充当互斥键。
    //
    // 预留不建立零长度占位文件。metadata、存在性查询、目录枚举和监听只
    // 观察 backend 真实状态；但同一协调域内针对同名条目的创建、复制、安全
    // 删除、改名和候选打开必须立即返回冲突，不等待复制完成。两个同进程
    // `copy_new` 只有一个取得预留，另一个不会重复搬运全部数据。显式非协调
    // 删除、库外调用、其它进程和未共享注册表的库副本不受该预留控制。
    //
    // 预留保持到发布明确完成、普通失败清理结束，或取消后的拥有型完成者
    // 到达安全停止点。它不能代替底层原子不替换：不合作参与者仍可抢先创建
    // destination，最终 publish 必须按真实结果失败且不得触碰竞争目标。
    //
    // # Source 稳定身份共享读取租约
    //
    // source 在打开但尚未登记稳定身份的窗口必须持有短期候选获取许可；汇合
    // 到进程级分片协调核心后，adapter 释放目录项许可，并为整个复制、取消
    // 收尾和在途底层访问保留共享复制读取租约。不同路径或硬链接指向同一
    // 稳定文件时必须汇合到同一核心，不能按 locator 各建一把锁。
    //
    // 该租约允许其它随机、顺序、增长和复制读取、长度或普通元信息查询、
    // 普通强刷新及严格尾部追加并发。追加只能扩展文件尾，复制不追随捕获 `L`
    // 之后的字节；若捕获长度时一个应用层追加记录只形成了可见前缀，本次
    // 复制可以包含该前缀，不承诺记录级原子快照。
    //
    // 同一稳定源对象的全文件覆盖、截断、任意待建立或活动 MMAP，以及安全
    // [`Self::remove_file`] 都必须立即冲突。默认 [`Self::rename`] 不主动查询
    // 内容租约；平台允许时，打开句柄在改名后继续读取原对象，平台拒绝时
    // 返回准确原生错误。非协调删除和外部操作不受租约约束，但不得导致悬垂
    // 内存、双重关闭或重新绑定到后来对象。
    //
    // # Staging 的形成、身份与可见性
    //
    // 本地暂存文件必须在 destination 的同一物理父目录中原子排他创建；远端
    // 暂存对象、multipart upload 或等价资源必须位于同一原子发布域。实现
    // 可以用进程级高熵量和单调序号降低名称碰撞，但随机性不是正确性证明；
    // 每次创建仍须使用 `create_new` 等价原语，碰撞时有界重选，绝不覆盖、
    // 打开、复用或清理碰撞对象。
    //
    // 创建后立即按稳定身份登记内部 staging 排它租约。同一身份的公开读取、
    // 追加、覆盖、截断、普通强刷新、任意 MMAP、安全删除、改名和候选打开
    // 全部冲突；私有传输写入由该租约授权。同时登记父目录的直接子项变更
    // 许可，使受管空目录删除或父目录搬迁不能穿透，但不同名称的普通子项
    // 操作仍然可以并发。
    //
    // 发布前必须证明 staging 从空内容开始，恰好形成 source 的 `[0, L)`，
    // 逻辑长度精确为 `L`，并且普通异步写入管道已经排空且没有短写或完成
    // 错误。该门禁不包含 `fsync`、父目录同步或持久介质提交。满足全部条件
    // 后才可发起一次原子 `no-replace` publish。
    //
    // destination 在 publish 前不会暴露半成品，但本地同目录 staging 是真实
    // namespace 条目，可能被目录枚举、原生工具和监听者观察。首版不从流中
    // 过滤，也不公开 staging locator；调用方不得根据实现名称前缀推断所有权
    // 或盲目删除。库外句柄、其它进程和恶意同权限参与者不受内部租约控制，
    // 高熵名称不是安全沙箱。
    //
    // # Backend 路由与传输实现边界
    //
    // source 与 destination 可以属于不同 backend；只有 staging 与 destination
    // 必须共享原子发布域。组合 namespace 在开始时分别路由两端一次，不能在
    // 数据块之间改选 backend，也不能把一个公开 [`FileIo`] 句柄在 async-fs、
    // Fusio 或原生所有者之间来回转换。
    //
    // source 必须提供稳定读取和长度能力，destination 必须提供完整暂存及原子
    // 不替换发布；任一能力不足时返回 [`pi_result::ErrorKind::Unsupported`]。
    // 标准 `async_fs::copy` 和 Fusio 0.6.1 通用 `Fs::copy` 具有覆盖、元信息、
    // 完成证据或协议响应缺口，不能成为直接实现或兜底。
    //
    // 本地正确性基线使用 `async-fs` 专用 source/staging 句柄，加定长有界
    // `AsyncRead`/`AsyncWrite` 传输和平台专用 publish。它不调用公开
    // [`FileIo`] 的读取加 append：严格 append 表达正式目标的 `O_APPEND`，
    // 逐块调用还会重复 buffer 脱离、操作租约和错误包装。远端实现使用经过
    // 核验的 Fusio 具体能力或 backend 条件 API；reflink、`copy_file_range`、
    // Windows 专用复制和服务端 Copy 只能在合同等价时作为优化。
    //
    // # 主内容与元信息语义
    //
    // 本方法只复制 source 主逻辑内容，不承诺复制权限、所有者、时间、ACL、
    // 扩展属性、Windows 备用数据流、稀疏物理布局、远端标签、content type、
    // 版本历史或 backend 专有元信息。destination 使用目标 backend 的普通
    // 新文件/对象默认策略；实现不得因为采用平台或服务端快速复制而悄然提升
    // 或改变这项可移植合同。
    //
    // 成功的 [`CopyOutcome::content_byte_len`] 是目标主内容的精确逻辑长度 `L`，
    // 不是用户态、网络或设备实际搬运量。克隆、写时复制、稀疏复制和服务端
    // Copy 可以搬运更少物理字节，但必须返回相同逻辑结果。
    //
    // # 普通成功、失败与证据
    //
    // `Ok(CopyOutcome)` 只在完整目标的原子不替换发布已经明确成功时返回。
    // 已知成功不能因随后日志、结果包装或独立 staging 清理失败而降级成错误；
    // 单独暂存残留只能进入日志、指标或以后专用回收记录。
    //
    // 普通错误返回 [`CopyFailure`]。其中 [`crate::CopyTargetEvidence`] 只描述
    // 本次最终发布：能证明未发布时使用 `NotPublishedByOperation`；完整 staging
    // 已形成且 publish 已提交、但响应或提交结果确实无法判定时，使用
    // `PublicationUnknown { content_byte_len: L }`。后者仍只允许“本次未发布
    // 或完整发布”两种解释，绝不包含部分 destination。
    //
    // [`crate::CopyStagingEvidence`] 独立描述 adapter 可管理的暂存物：从未
    // 创建、创建后已经移除、普通错误完成时已知存在或无法证明。两类证据都
    // 是错误完成点的历史事实，不是 locator 的实时查询，也不授予调用方删除
    // 当前同名对象的权利。接口刻意不提供 `is_retry_safe`；重试还取决于错误
    // 分类、当前目标、源变化、外部参与者和业务恢复协议。
    //
    // 普通失败返回前，adapter 对仍能按稳定身份识别的 staging 作一次安全的
    // 尽力清理，不无界重试。如果主流程和清理同时失败，
    // [`CopyFailure::error`] 保持主错误分类，完整清理 report 作为带
    // `Stage("copy_staging_cleanup")` 的第二个 attachment 保留；暂存证据仍
    // 是清理状态的权威结构化结论。
    //
    // 无效 locator、源不存在或类型错误、目标已存在、父容器缺失、协调冲突、
    // 权限不足、空间或配额不足、意外文件尾、短写、资源耗尽、backend 能力
    // 不足、远端协议及底层 I/O 错误都必须结构化返回。满足接口前置条件的
    // 可报告情况不得 panic；长度、偏移或内存窗口转换溢出也必须在副作用前
    // 返回错误。
    //
    // # 取消、Drop 与完成所有权
    //
    // 从未轮询的 Future 不得取得许可、打开对象或创建 staging。发布尚未
    // 提交时观察到取消，adapter 必须停止提交新传输工作且不得再发布目标，
    // 并只对稳定识别的暂存物作一次尽力清理。`Drop` 本身始终非阻塞，不执行
    // 同步文件 I/O、网络请求或等待。
    //
    // 原生调用、阻塞任务、远端请求或原子 publish 一旦提交且不能抢占，调用方
    // Drop Future 只表示停止等待；完全拥有状态的内部完成者必须继续到安全
    // 停止点，保持全部许可到真实底层访问结束。publish 尚未提交时完成者不能
    // 擅自提交；已经提交时不能靠取消假装撤销，调用方必须按 destination 可能
    // 不存在或已经完整发布处理。
    //
    // 取消没有 [`CopyFailure`] 返回通道，也不承诺暂存物一定清理。强制终止
    // 进程同样可能留下部分或完整 staging；其专项发现与回收属于以后独立设计，
    // 不能按名称前缀自动删除。
    //
    // # 进程内与跨进程协调边界
    //
    // 本方法只加入普通进程内协调域，不接收 [`Self::CrossProcessAuthority`]，
    // 不创建 sidecar、协议记录或 `fs4` 锁。source 稳定身份已经进入 authority
    // 域，或者 destination 条目存在有效、删除中、已删除、身份冲突等协调
    // 记录时，必须返回冲突；不能自动升级或绕过协议。仅配置全局协调根并不
    // 使所有普通目标自动受管。
    //
    // 其它进程、库外句柄和另一份未共享注册表的库实例不受普通许可约束。
    // 原子 no-replace 仍防止它们的既有 destination 被覆盖，但 source 内容、
    // staging 访问和跨进程操作顺序没有统一保证。首版不提供协调式复制重载；
    // 该能力需要单独冻结双端授权、锁序、目标实例发布和恢复状态机。
    //
    // # 幂等性、副作用、持久性与成本
    //
    // 本方法不是状态或响应幂等操作。一次成功后用相同参数重试通常返回目标
    // 已存在；publish 结果未知时盲目重试可能与本次已发布目标或后来参与者
    // 竞争。空文件复制同样会创建 namespace 条目并更新时间、日志或远端状态，
    // 不是无副作用的查询。
    //
    // 本方法会打开源和父目录、创建及写入内部 staging、更新进程内协调表、
    // 提交 namespace 或远端对象发布、尝试清理，并可能分配 buffer、使用阻塞
    // 设施及记录日志或指标，因此不是纯函数。它不调用用户回调，不自动创建
    // 父目录，不发送伪造的监听事件，也不在失败后删除竞争 destination。
    //
    // 成功只证明正常运行中的原子不替换发布，不隐式执行 source 或 staging
    // `sync_all`、父目录同步、卷刷新、远端持久化屏障或多对象事务。接口不
    // 保证掉电、操作系统崩溃或重启、失信控制器/固件/缓存、介质损坏、bit rot
    // 或硬件故障后的数据和名称持久性；Linux tmpfs 可以满足运行期发布语义，
    // 但本身不因此成为非易失存储。
    //
    // 有界流式实现通常承担 `O(Ps + Pd + L)` 时间和 `O(C)` 工作内存，`Ps`、
    // `Pd` 是两端定位成本，`C` 是私有有界窗口；接口不承诺固定窗口、零复制、
    // 零分配或固定延迟。服务端复制或文件系统克隆可以减少用户态 `O(L)` 搬运。
    // 进程级条目和稳定身份注册表必须分片，普通准入期望 `O(1)`，复制热循环
    // 不重复查询全局表。同步临界区只允许状态和许可转移，禁止 I/O、`.await`、
    // 用户回调、可能阻塞的日志及无界分配。
    //
    // 可能阻塞的本地打开、读写、身份查询、发布和清理必须由 adapter 的有界
    // 阻塞设施承载，不能长期占用调用方执行器的 poll 线程。内部设施选择不
    // 改变 Future 的运行时无关公共合同。
    //
    // # 参考基线与采纳差异
    //
    // 本合同于 2026-08-31 核验了 Rust 标准库
    // [`std::fs::copy`](https://doc.rust-lang.org/std/fs/fn.copy.html)、
    // [`OpenOptions::create_new`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create_new)、
    // async-fs 2.2.0
    // [`copy`](https://docs.rs/async-fs/2.2.0/async_fs/fn.copy.html)、Linux
    // [`renameat2(RENAME_NOREPLACE)`](https://man7.org/linux/man-pages/man2/rename.2.html)、
    // Microsoft
    // [`FILE_RENAME_INFO`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_rename_info)
    // 以及 AWS S3
    // [条件写](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html)。
    // 本方法采纳它们能够证明的专用打开、条件提交和原子发布能力，但拒绝
    // std/async-fs 的覆盖式 copy、Fusio 通用覆盖 copy、检查后覆盖和跨域
    // copy-and-delete。依赖或 backend 能力变化时必须重新核验这些差异。
    /// 把一个源文件复制为严格不替换的新目标。
    ///
    /// 本方法跟随源的最终符号链接，固定同一源对象的一次逻辑长度 `L`，并只
    /// 复制 `[0, L)`；之后的尾部追加不会进入结果。受管的覆盖、截断、映射和
    /// 安全删除在复制期间冲突，但库外或未协调修改不构成统一内容快照保证。
    /// 目标最终名称只会以完整内容出现；目标已存在时失败且不得修改。它不
    /// 复制目录，也不承诺保留权限、时间、扩展属性、稀疏布局或其它元信息，
    /// 除非未来另有明确合同。成功返回 [`CopyOutcome`]；失败通过
    /// [`CopyFailure`] 分别说明最终目标和本次操作所管理临时资源的可证明
    /// 状态。取消后结果可能不确定，调用方不得
    /// 盲目重试。成功不隐含掉电或系统崩溃持久性保证。
    fn copy_new<'a>(
        &'a self,
        source: &'a Self::Locator,
        destination: &'a Self::Locator,
    ) -> impl Future<
        Output = pi_result::RawResult<CopyOutcome, CopyFailure>,
    > + Send + 'a;

    // 跨进程协调式排他创建一个空的普通文件，并原子建立其协调授权与首个资源。
    //
    // 本方法把普通排他创建、稳定文件身份核验、跨进程协调协议发布、当前进程
    // 协调核心安装以及首个 [`Self::File`] 的建立放入一个受控流程。它用于调用
    // 方从文件诞生起就必须获得跨进程协调保证的场景；不能用
    // [`Self::create_new`] 成功后再调用
    // [`Self::establish_cross_process_authority`] 拼接出等价语义，因为两次调用
    // 之间会出现目标已经可见、协调协议却尚未发布的窗口。
    //
    // # Safety
    //
    // 调用方必须保证，从本 Future 开始轮询，到成功结果及其派生的最后一个
    // 文件资源、映射句柄和取消后在途操作真实结束为止：
    //
    // - 所有可能读取、追加、覆盖、截断、映射、删除、改名或替换目标的相关
    //   进程、库实例和原生句柄都遵守同一套兼容的协调规则；
    // - 所有合作参与者把全局协调根策略解析到同一个物理锁域；
    // - 不存在绕过协议的普通文件句柄、原生映射、namespace 操作或不受管
    //   adapter；
    // - 不受信任主体不能删除、替换、伪造或篡改协调目录、协议记录和租约；
    // - 目标文件、父目录和协调根位于 adapter 明确证明支持稳定身份、排他
    //   创建、原子发布和所需文件锁语义的文件系统上；
    // - 路径别名、符号链接、硬链接、Windows 重解析点、挂载命名空间和文件
    //   身份复用满足 adapter 公开声明的边界。
    //
    // `fs4` 等咨询锁只能约束合作进程，不能证明这些外部事实。违反承诺可能
    // 使本方法签发的授权失去真实性，并破坏后续安全协调式 MMAP 所依赖的
    // 文件长度、身份和范围不变量。因此 `unsafe` 集中在授权签发入口；成功
    // 返回后的协调式打开和映射不要求重复书写同一承诺。
    //
    // 本方法不是路径沙箱，也不承诺抵御绕过协议的恶意父目录替换。实现仍须
    // 使用稳定父目录和目标句柄、前后身份核验以及合作式门禁缩小竞态窗口，
    // 不能因为调用点是 `unsafe` 就跳过能够在库内完成的验证。
    //
    // # 参数、所有权与返回值
    //
    // `locator` 按所有权传入。Future 可以把它移动给阻塞任务或取消后的内部
    // 完成所有者，避免为了满足异步生命周期而强制克隆定位符。调用完成后不
    // 返还 locator；需要保留副本的调用方必须在调用前显式克隆。
    //
    // `access` 按值指定成功结果中首个 [`Self::File`] 唯一获准的
    // [`FileAccessMode`]。它只选择以后允许申请的操作角色；本方法本身不执行
    // 内容读取、追加、覆盖、截断、建图或刷新。新目标在普通可观察语义上是
    // 空文件，但成功不承诺目录项已经完成抗掉电持久化。
    //
    // 成功返回 [`CrossProcessCreateSuccess`]。其中授权和文件都拥有全部必要
    // 状态，不借用 namespace、locator、创建 Future 或临时原生句柄。授权可
    // 继续交给 [`Self::open_with_cross_process_authority`]；首个文件则已经
    // 绑定相同的私有协调核心和目标稳定身份。
    //
    // `locator` 和 `access` 被消费不代表创建一定提交。失败时调用方必须通过
    // [`CreateFailure::target_evidence`] 判断本次操作是否可能已经建立目标，
    // 不能仅根据错误种类推断文件是否存在。
    //
    // # 严格排他创建与符号链接
    //
    // 目标位置必须在本次原生排他创建的线性化点之前不存在任何目录项。普通
    // 文件、目录、符号链接、悬空符号链接、Windows 重解析点以及其它特殊
    // 对象都构成“已经存在”；实现不得自动打开、覆盖、截断、跟随最终链接或
    // 加入该对象已有的协调域。
    //
    // 父路径的中间分量按 adapter 公开的平台规则解析。实现必须把解析得到的
    // 物理父目录绑定到原生目录身份锚点，以其稳定身份而不是 locator 文本
    // 作为 bootstrap 协调键，并从排他创建前保持父目录门禁，直到协议发布和
    // 返回资源均已准备完成。Linux adapter 应优先使用锚定目录句柄的相对
    // 排他创建；Windows adapter 必须至少使用父目录句柄和前后稳定身份核验。
    //
    // 原生排他创建成功并返回有效 owning handle 的瞬间是目标创建提交点。
    // 创建后必须从该句柄取得目标类型和稳定身份，建立私有身份锚点，并在
    // 签发授权前重新核验父目录身份、locator 当前目标身份和物理协调根身份。
    // 后置核验失败不能被改写成“尚未创建”，也不得触发补偿删除。
    //
    // # 协调协议发布
    //
    // 内置本地协议先冻结进程全局的
    // [`crate::CrossProcessCoordinationRoot`]，再按父目录稳定身份取得 bootstrap
    // 门禁，创建目标并按目标稳定身份进入正式初始化门禁。协议状态遵循：
    //
    // ```text
    // Absent -> Preparing { generation, target_incarnation } -> Published { ... }
    // ```
    //
    // 只有完整且验证通过的 `Published` 可以签发授权。发布记录必须先在同一
    // 协调目录内完整生成，再通过不覆盖既有目标的原子安装成为不可变记录；
    // 原子安装是协议发布的线性化点。记录绑定协议族、记录格式版本、协调规则
    // 版本、持久协调代次、目标实例代次、目标稳定身份和物理协调根身份。
    // 未知版本默认拒绝，不能猜测、自动降级或覆盖。
    //
    // `generation` 标识这一个持久协调目录实例；只要该目录仍是同一协议域，
    // 它就不因资源释放、进程退出或目标文件删除重建而轮换。
    // `target_incarnation` 则标识该受管定位符下某一次具体文件生命周期。
    // 协调式删除必须保留协调目录，并按以下逻辑状态推进旧实例：
    //
    // ```text
    // Published { generation, target_incarnation, ... }
    //     -> Removing { generation, target_incarnation, ... }
    //          |-- 旧身份仍存在或目标不存在 --> Removed { ... }
    //          `-- 定位符指向不同稳定身份 --> IdentityConflict { ... }
    // ```
    //
    // `Removing` 记录的原子发布是协调式删除的不可撤销逻辑提交点。发布前
    // 取消或失败不得移除目标绑定；发布后，调用方取消只表示停止等待，不能
    // 撤回删除意图。当前进程的拥有型完成所有者必须继续到安全停止点；如果
    // 整个进程退出，下一合作进程必须在取得相同排它门禁后恢复该意图：旧
    // 稳定身份仍位于受管位置时继续删除，目标已经不存在时发布 `Removed`。
    // 恢复时发现另一稳定身份时绝不能删除该新对象，也不能把旧授权迁移给它；
    // 实现必须原子发布持久化的 `IdentityConflict` 隔离状态。该状态不是删除
    // 成功或正常退役：所有普通协调式打开、映射、删除、重建和授权建立都
    // 必须明确失败，只有以后单独设计的显式修复接口才能解除隔离。
    //
    // 正常合作协议中，`Removing` 已经排除新的受管创建和替换，因此上述分支
    // 不进入普通热路径。它用于阻止旁路重建、目录替换、文件系统状态回退、
    // 协议篡改或其它失信行为被自动掩盖。诊断可以保存经过验证和脱敏的身份
    // 摘要，但不能把可伪造的路径文本当成冲突证明。
    //
    // 身份分歧必须按删除提交点前后分别解释。在 `Published` 状态下，目标
    // 缺失或稳定身份不同都说明账面状态与真实 namespace 已经分叉；实现必须
    // 在不发布 `Removing`、不删除当前对象的前提下进入 `IdentityConflict`，
    // 并分别记录 `Missing` 或 `DifferentIdentity` 原因。该次删除调用使用
    // [`crate::RemoveTargetEvidence::NotRemovedByOperation`]，因为它没有跨过
    // 删除提交点。
    //
    // 在 `Removing` 状态下，目标缺失是不可撤销删除已经完成底层移除、但尚
    // 未发布终态的合法恢复情形，必须推进到 `Removed`。只有定位符指向不同
    // 稳定身份时才进入 `IdentityConflict`；此时旧目标可能已经由先前执行者
    // 移除，失败证据必须使用 [`crate::RemoveTargetEvidence::Unknown`]，不能
    // 把当前新对象的存在误报为旧操作尚未删除目标。
    //
    // 推进残留 `Removing` 只能通过两个显式入口：持有匹配旧授权的协调式
    // 单文件删除方法，或者以后单独声明的 `unsafe` 单文件删除恢复方法。后者
    // 按 locator 重新发现持久协议，服务于进程重启后已经没有内存中授权的
    // 情形；它只能恢复已提交意图，绝不能把 `Published` 推进为 `Removing`。
    //
    // 普通协调式打开、创建、映射和授权建立发现 `Removing` 时必须返回明确
    // 的删除恢复中错误，不得在看似无关的调用中隐式删除目标。恢复入口之所以
    // 仍为 `unsafe`，是因为新进程没有可继承的授权值，调用方必须重新承诺
    // 所有相关进程、旁路句柄和映射仍服从同一跨进程协调协议。
    //
    // 显式恢复方法是状态幂等的：`Removing` 完整推进到 `Removed` 后返回成功；
    // 当前记录已经是同一旧实例的 `Removed`，并且受管位置仍为空时也返回
    // 成功，以允许响应丢失后的安全重试。该规则不扩展为“路径不存在即成功”：
    // 缺少合法协调记录必须报错；当前记录已经发布新实例时不得影响新文件；
    // `Removed` 下出现未经协调的新对象时必须转入 `IdentityConflict`。
    //
    // 持匹配授权的协调式单文件删除采用相同的目标实例幂等规则：它可以从
    // `Published` 发起删除、从 `Removing` 继续删除，也可以确认同一实例已经
    // 合法处于 `Removed` 且位置仍为空。授权绑定的实例已经被新的
    // `target_incarnation` 取代，或者已退役位置出现旁路对象时，旧授权必须
    // 失败，不能把幂等性扩展成对 locator 文本的无条件成功。普通
    // [`Self::remove_file`] 仍保持严格存在语义，不继承该例外。
    //
    // 上述状态机只提供合作进程协议和普通进程崩溃后的恢复依据，不承诺在
    // 掉电、操作系统崩溃、失信硬件缓存或硬件损坏后仍保留最新状态。需要
    // 更强持久性时必须由以后单独设计的显式发布与目录同步合同提供，不能从
    // 原子安装动作本身推导抗掉电保证。
    //
    // 同一定位符以后可以由显式协调式创建协议重新使用，但新文件必须在同一
    // `generation` 下取得全新的 `target_incarnation` 和稳定文件身份。旧实例
    // 永久保持已退役；旧授权不得因定位符文本相同而控制、打开、映射或删除
    // 新文件。协议记录和协调目录不随公开授权 `Drop` 删除；历史记录的离线
    // 回收属于以后单独设计的管理功能。
    //
    // 合法且兼容的 `Published` 是可长期复用的协调目录实例，不因最后一个
    // 进程内资源 Drop 而自动换代。授权只保存稳定身份值，不永久握住目标
    // 文件句柄；活动文件资源和映射自行持有必要身份锚点并维持生命周期租约。
    // 动态 MMAP 范围租约则按原生锁的真实存活状态回收，不靠 PID、时间戳或
    // 每次打开时轮换代次判断活性。
    //
    // 发现只有 `Preparing` 时，必须先证明当前进程内没有初始化者并成功取得
    // 跨进程排他初始化门禁，才能废弃旧代次并重新开始。合法 `Published`
    // 与残留 `Preparing` 同时存在时以 `Published` 为准；损坏或不兼容的发布
    // 记录必须报错，不能由普通创建流程自行修复。
    //
    // # 成功条件与文件资源权限
    //
    // `Ok` 只能在以下事实全部成立后产生：
    //
    // - 原生排他创建已经提交；
    // - 目标已经证明为支持范围内的普通文件；
    // - 目标稳定身份及私有身份锚点已经建立；
    // - 合法 `Published` 已经原子发布或经过完整验证后复用；
    // - 当前进程的分片稳定身份注册表已经安装或汇合到唯一协调核心；
    // - 返回授权和首个独立文件资源均已完整构造。
    //
    // 创建原语为了建立新文件可能需要写权限，但返回的公开文件只能保留
    // `access` 角色所需的最小权限。如果创建句柄带有更宽权限，实现必须在
    // 持有目标锚点和协调门禁时独立打开并复核一个角色正确的新句柄，再关闭
    // 未交付的创建句柄。不得用 `dup`、`DuplicateHandle`、`try_clone` 或从
    // 同一 raw handle 重复构造 owning file 来伪造独立资源。
    //
    // # 错误与目标状态证据
    //
    // locator 无效、父目录不存在、目标已经存在、访问角色不支持、权限不足、
    // 空间或配额不足、文件系统能力不足、协调门禁冲突、协议不兼容或损坏、
    // 身份核验失败、资源耗尽和底层 I/O 失败都必须通过 [`CreateFailure`]
    // 返回；可报告条件不得 panic。
    //
    // adapter 必须按目标排他创建提交点填写证据：
    //
    // - 提交前失败使用 [`crate::CreateTargetEvidence::NotCreatedByOperation`]；
    // - 提交后任何失败使用
    //   [`crate::CreateTargetEvidence::CreatedByOperation`]；
    // - 只有底层确实无法证明提交结果时才允许使用
    //   [`crate::CreateTargetEvidence::Unknown`]。
    //
    // `CreatedByOperation` 不证明错误返回时目标仍位于原 locator，也不证明它
    // 尚未被另一参与者观察或改名。实现不能为了提供整洁外观而自动删除已经
    // 建立的目标。`Unknown` 也不能用于掩盖 adapter 缺少本可执行的句柄核验。
    //
    // 内置首版只保证 Windows 10 x64 本地普通文件、Linux 本地普通文件、
    // Linux tmpfs，或者经过相同能力证明的 adapter。远端对象、SMB、NFS、
    // CIFS、UNC、FUSE、WSL 挂载转发路径、设备、管道、套接字和目录不能因
    // 签名通用就被推定支持；能力不充分时必须在目标创建前失败。
    //
    // # 取消与完成所有者
    //
    // 从未轮询的 Future 不得冻结配置、创建目标、建立协调目录或登记资源。
    // 取得准入许可前取消必须无文件副作用；原生排他创建尚未提交时，内部
    // 操作可以停止并释放临时门禁。
    //
    // 一旦阻塞创建、目录操作或文件锁任务已经提交，调用方丢弃 Future 只
    // 表示停止等待。内部拥有型完成所有者必须接管 locator、临时句柄和全部
    // 操作许可：创建尚未提交时安全停止；创建已经提交时继续到合法发布或
    // 完整、静止、可恢复的失败状态。它不得自动删除目标，也不得留下半有效
    // 授权、幽灵进程内租约或仍会访问已释放数据的后台任务。
    //
    // Drop 不同步等待后台完成。取消没有返回 [`CreateFailure`] 的通道，因此
    // 调用方在提交点不确定时必须按“目标可能已经建立”处理；稍后恢复已有
    // 目标应显式使用 [`Self::establish_cross_process_authority`]，不能盲目
    // 重试本排他创建方法。
    //
    // # 并发、锁顺序与运行时
    //
    // 返回 Future 为 `Send + 'a`，可以在借用 namespace 的期间跨工作线程
    // 迁移，但不承诺 `Sync` 或 `'static`。需要 `Send + 'static` 顶层任务的
    // 调用方可以让外层 `async move` 拥有 namespace，再在任务内部调用本方法。
    // 本接口不要求 Tokio、async-std、smol、Monoio 或其它具体运行时类型。
    //
    // 协调式创建和已有目标授权建立必须遵守统一门禁顺序：进程内父目录许可、
    // 跨进程父目录 bootstrap、进程内目标初始化、跨进程目标初始化，最后才
    // 短暂访问分片注册表。多父目录和多文件操作分别按稳定身份全序获取；禁止
    // 反向获取或原地升级锁。
    //
    // 进程内父目录许可可以通过有界异步队列等待，等待期间不得阻塞执行器
    // 线程；跨进程 bootstrap 使用非阻塞尝试，冲突时在目标提交前明确失败。
    // 取得跨进程父目录门禁后不得等待另一个进程内或跨进程目标门禁；冲突时
    // 必须反向释放已有许可并按创建提交点报告证据。
    //
    // 分片注册表临界区只允许稳定身份比较、`Weak` 升级和核心安装。锁内禁止
    // 文件 I/O、`.await`、`fs4`、建图、用户回调、可能阻塞的日志和无界分配。
    // 同步创建、身份查询、协议文件操作和必要清理必须由有界阻塞设施承载，
    // 不能直接占用调用方执行器的 poll 线程。
    //
    // # 副作用、幂等性、持久性与成本
    //
    // 本方法不是纯函数。它可以冻结全局协调根策略，创建空目标和协调目录，
    // 写入不可变协议记录，打开目标、父目录与 sidecar 句柄，取得文件锁，并
    // 修改进程内分片注册表、引用计数、日志和指标。失败后完整且静止的协议
    // 残留可以保留，不能为了回滚外观删除可能已经被其它参与者观察的对象。
    //
    // 本方法既不具备状态幂等性，也不具备响应幂等性。一次成功后以同一
    // locator 重试通常得到 `AlreadyExists`；结果未知时直接重试可能把原成功
    // 错判成新失败。需要加入已经存在的目标时必须使用独立的授权建立入口。
    //
    // 成功只表示普通系统调用和协调协议完成，不执行隐式 `sync_data`、
    // `sync_all`、目录强同步或 MMAP 刷新，也不保证掉电、操作系统崩溃、失信
    // 硬件缓存或硬件损坏后的持久性。Drop 同样不补做刷新、协议换代或协调
    // 目录删除。
    //
    // 本地普通成本为 `O(P)` 路径解析和少量原生打开/身份/锁系统调用、一个
    // 有界协议记录的读写，以及期望 `O(1)` 的分片注册表操作；`P` 是路径长度
    // 或组件数。同一物理父目录中的协调式创建会在 bootstrap 冷路径短时串行，
    // 不同父目录可以并行。建立授权时不扫描全部历史 MMAP 范围记录；动态
    // 范围残留在真正申请范围准入时核验和回收。
    //
    // 协议解析必须先验证固定上限，再分配内存，不能让损坏记录触发无界分配。
    // 本方法不调用用户代码，也不承诺固定延迟、公平调度、零分配或零系统调用；
    // 这些冷路径成本不得传播到成功文件的普通读取或 MMAP 字节访问热路径。
    /// 排他创建空文件，并同时建立跨进程协调授权和首个文件资源。
    ///
    /// 最终位置必须不存在；成功返回的授权与文件资源绑定同一目标实例。该
    /// 方法用于目标从首次可见起就必须参加跨进程协作的场景，不能由普通创建
    /// 与事后建立授权拼接出等价原子语义。失败通过 [`CreateFailure`] 报告目标
    /// 创建证据，取消后目标或协调状态可能已经提交。
    ///
    /// # Safety
    ///
    /// 调用方必须保证所有会影响目标身份、长度、内容、映射或名称的进程均
    /// 遵守同一协调协议，且协调存储位置不会被不受信任主体替换或篡改。库外
    /// 原生访问、协议版本不一致或不受信任参与者会破坏该安全前提。同一物理
    /// 目标还必须始终通过相同的物理父目录和原生末级文件名参与协议；不得用
    /// 不同硬链接名建立或访问同一协调目标。
    unsafe fn create_new_coordinated<'a>(
        &'a self,
        locator: Self::Locator,
        access: FileAccessMode,
    ) -> impl Future<
        Output = pi_result::RawResult<
            CrossProcessCreateSuccess<
                Self::CrossProcessAuthority,
                Self::File,
            >,
            CreateFailure,
        >,
    > + Send
           + 'a;

    // 为一个已经存在的文件建立或加入跨进程协调域，并返回拥有型授权。
    //
    // 本方法位于定位符解析与协调式文件资源打开之间。它核验目标的稳定文件
    // 身份，原子冻结全局协调根目录策略，创建或打开目标专属协调目录，核验
    // 协议状态与目标实例代次，并把相同文件汇合到当前进程的稳定身份协调
    // 核心。成功结果本身不授予文件内容读写权限；调用方随后通过独立的协调
    // 式打开方法借用该授权并取得 [`Self::File`]。
    //
    // 本方法只接受已经存在的普通文件。协调式新文件创建不能由“普通创建后
    // 再调用本方法”拼接，因为两步之间存在未协调窗口；协调式排他创建必须
    // 使用 [`Self::create_new_coordinated`]，在一个受控流程中建立目标、稳定
    // 身份、授权和首个文件资源。
    //
    // # Safety
    //
    // 调用方必须保证，从本 Future 开始建立协调状态，到成功授权派生出的
    // 最后一个文件资源、映射和取消后在途操作真实结束为止：
    //
    // - 所有可能读取、修改、截断、替换、删除、改名或映射目标文件的相关
    //   进程和库实例都遵守同一版本的协调协议；
    // - 所有合作进程选择解析到同一个物理锁域的全局协调根目录策略；
    // - 不存在绕过协议的普通文件句柄、映射、命名空间操作或不受管 adapter；
    // - 目标文件与协调根目录位于本 adapter 明确支持的本地文件系统上；
    // - 不受信任主体不能替换或篡改协调目录、协议文件和租约记录；
    // - 路径别名、符号链接、硬链接、挂载命名空间和稳定身份复用满足本
    //   adapter 公开声明的限制。
    //
    // 这些条件不能由 `fs4` 或普通操作系统文件锁完整证明。违反条件可能使
    // 后续安全的协调式内存映射访问依赖一个已经失效的文件稳定性假设，因此
    // 本方法必须是 `unsafe`；它只是把责任集中到授权建立点，没有消除底层
    // 映射设施的真实外部前置条件。
    //
    // # 参数、借用与异步运行时
    //
    // `locator` 只用于解析当前目标，不按值消费。Future 在同一个 `'a` 内
    // 借用 namespace 与定位符，返回值则拥有全部必要状态并满足 `'static`。
    // 返回 Future 为 `Send`，可以在借用期内跨工作线程迁移，不绑定 Tokio、
    // async-std、Monoio 或其它运行时。
    //
    // 需要顶层任务为 `Send + 'static` 的调用方可以让 `async move` 任务拥有
    // namespace 和定位符，再在任务内部借用并等待本方法。adapter 不得让
    // 任何借用越过 Future 的真实生命周期；不能安全取消的阻塞操作必须由
    // 内部拥有型完成所有者接管。
    //
    // # 成功、重复建立与活动资源
    //
    // 成功授权必须绑定当前 namespace/backend 实例、目标稳定文件身份值、目标
    // 实例代次、已解析的全局协调根目录身份和协议版本。它已经加入当前进程
    // 的协调核心，但自身不计为活动文件资源，不持有阻止删除的共享生命周期
    // 租约，不永久持有目标文件句柄，也不长期持有某一项读取、追加、映射或
    // 破坏性操作的独占锁。身份验证临时句柄必须在成功返回前关闭。
    //
    // 对同一稳定身份重复调用可以返回另一个公开授权值；实现应在重新核验
    // locator、文件身份、根目录和协议后共享同一个私有引用计数核心。该行为
    // 不等于为公开类型实现 `Clone`，每次建立都可能发现新的替换、权限、
    // 协议或后端错误。
    //
    // 如果当前进程已经存在同文件的活动非协调资源，本方法必须在提交协调域
    // 前返回冲突，不能静默升级已经交给调用方的资源。反向地，授权或其派生
    // 对象存活时，后续同文件非协调打开也必须失败；否则当前进程自身就会
    // 绕过向其它合作进程承诺的 sidecar 协议。
    //
    // # 错误与副作用
    //
    // 不存在、非普通文件、不支持的远端或文件系统、自定义根目录无效、权限
    // 不足、身份歧义、协议不兼容或损坏、进程内模式冲突和底层 I/O 失败均
    // 通过 [`pi_result::Error`] 返回，本方法不得因可报告条件 panic。
    //
    // 本方法不得修改目标文件内容或长度，但可能创建目标专属协调目录、协议
    // 文件、门闩文件和租约容器，打开 sidecar 句柄，并更新进程内稳定身份表、
    // 日志和指标。失败后已经形成的合法空协调目录或完整协议文件可以保留；
    // 实现不能为了回滚外观而删除可能已经被另一合作进程加入的协调对象。
    //
    // # 取消与资源收尾
    //
    // 从未轮询的 Future 不得产生副作用。在初始化准入前取消不得创建协调
    // 状态；一旦目录创建、文件锁或阻塞系统调用已经提交，内部完成所有者
    // 必须继续到安全停止点，最终释放临时操作锁和进程内初始化预留。取消后
    // 可以留下完整且没有活动租约的协调目录，但不能产生可被观察为成功的
    // 半初始化授权，也不能要求调用方继续轮询已丢弃的 Future 才能恢复状态。
    //
    // 同步目录和文件锁操作必须由内部阻塞设施承载，不能直接阻塞调用方异步
    // 执行器的 poll 线程。
    //
    // # 幂等性与成本
    //
    // 本方法在“加入同一个协调域”的逻辑效果上可重复，但不是无副作用的纯
    // 幂等函数：每次调用都可以重新核验外部状态、产生系统调用和独立错误，
    // 并返回新的公开授权值。它属于冷路径，可能执行多次元信息查询、目录
    // 打开、文件锁和协调记录扫描，不承诺零分配、零系统调用或固定延迟。
    /// 为一个已经存在的文件建立或加入跨进程协调域。
    ///
    /// 成功授权绑定本次核验到的目标实例，不计为已打开文件资源，也不允许与
    /// 其它定位符或同名重建对象互换。目标不存在、身份不稳定、协议不兼容或
    /// 当前存在不兼容的受管资源时返回错误。
    ///
    /// # Safety
    ///
    /// 调用方必须保证所有会影响目标身份、长度、内容、映射或名称的进程均
    /// 遵守同一协调协议，且协调存储位置不会被不受信任主体替换或篡改。同一
    /// 物理目标还必须始终通过相同的物理父目录和原生末级文件名参与协议；
    /// 不得用不同硬链接名建立或访问同一协调目标。
    unsafe fn establish_cross_process_authority<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<
        Output = pi_result::Result<Self::CrossProcessAuthority>,
    > + Send
           + 'a;

    // 使用既有跨进程授权独立打开一个角色明确的协调式文件资源。
    //
    // 本方法不再接收 locator：[`Self::CrossProcessAuthority`] 已经绑定目标
    // 稳定文件身份、目标实例代次、当前 namespace/backend 实例、受管定位
    // 信息、协调根目录身份和协议版本。adapter 必须从授权内部取得受管位置，
    // 执行一次新的底层打开，并在返回前把新句柄的稳定身份、当前 `Published`
    // 状态与授权绑定的目标实例代次重新核对。删除、替换、外部改名、身份复用，
    // 以及处于 `Removing` 或 `Removed` 的旧实例，都不得使授权静默转移到路径
    // 上的另一个文件。
    //
    // `access` 按值指定新资源唯一获准的 [`FileAccessMode`]。打开成功只建立
    // 以后申请该类操作的能力，不代表读取、追加、映射或截断已经开始；空闲
    // 资源不得长期占用这些操作的冲突租约。
    //
    // # 安全边界
    //
    // 本方法是安全 Rust interface。无法由安全代码任意构造的 `authority`
    // 已把外部合作承诺集中到
    // [`Self::establish_cross_process_authority`] 或
    // [`Self::create_new_coordinated`] 的 `unsafe` 调用点。本方法仍必须验证
    // 授权属于当前 namespace，并在每次新打开后复核稳定身份；类型相同或
    // 协议文件仍存在都不能替代这些检查。
    //
    // 调用方若违反建立授权时承诺的进程、旁路句柄、文件系统或锁域条件，
    // 安全责任追溯到该 `unsafe` 建立点，不要求每次协调式打开再次书写
    // `unsafe`。adapter 自身使用底层原生句柄和映射设施时仍必须履行其全部
    // 安全合同。
    //
    // # 独立资源与底层打开
    //
    // 每次成功调用必须产生新的逻辑资源和独立的底层打开状态，不能克隆已有
    // 公开资源，也不能通过 `dup`、`DuplicateHandle`、`File::try_clone` 或
    // 等价方式复制同一个打开状态。多个资源可以共享授权的私有协调核心，
    // 但公开 [`Self::File`] 仍不可克隆。
    //
    // 对 [`FileAccessMode::Append`]，本地 adapter 必须执行新的严格追加模式
    // 打开；对读取、映射和截断角色，则只申请实现该角色所需的最小权限。
    // adapter 必须在打开阶段确认角色可实现：完全不支持时返回
    // [`pi_result::ErrorKind::Unsupported`]，系统权限不足时返回相应权限错误，
    // 不能返回一个已知核心操作必然失败的伪资源。
    //
    // [`FileAccessMode::Truncate`] 只授权以后显式缩短文件；本方法本身不得把
    // 文件清空或改变长度。[`FileAccessMode::ReadMmap`] 和
    // [`FileAccessMode::ReadWriteMmap`] 也只准备建图权限，不在打开阶段创建
    // 映射或范围租约。
    //
    // # 并发与操作租约
    //
    // 同一个授权可以由多个线程共享借用并发调用，分别获得独立资源。打开
    // 过程只取得足以防止受管删除、替换、改名和身份切换的短期准入租约；
    // 成功返回后，资源会作为活动所有者维持按进程聚合的跨进程共享生命周期
    // 租约，因而即使暂时空闲也会阻止协调式删除；它不会仅因潜在操作角色
    // 阻塞活动映射、读取或追加。
    //
    // 例如活动只读映射存在时仍可打开新的 append 资源，真正追加也按已
    // 冻结规则允许与既有映射并存；可以提前打开 truncate 资源，但实际截断
    // 必须因活动映射而返回冲突。adapter 的 Windows sharing flags 或其它
    // 平台打开选项不得制造比公共合同更强的资源生命周期互斥。
    //
    // 同一进程中第一个活动所有者取得共享生命周期租约，后续资源只复用私有
    // 协调核心并增加活动计数；最后一个资源、映射、候选获取或取消后的在途
    // 完成所有者退出时释放该租约。该聚合只优化生命周期协调，不得把需要
    // 独立原生打开状态的多个 [`Self::File`] 合并成同一个底层文件句柄。
    //
    // # 错误与副作用
    //
    // 授权属于另一 namespace、目标身份已变化、受管位置不可访问、协议状态
    // 失效、访问角色不受支持、权限不足、资源耗尽以及底层打开失败均通过
    // [`pi_result::Error`] 返回，本方法不得因可报告条件 panic。
    //
    // 成功或失败过程中可以新开目标句柄、打开或复用 sidecar 句柄、增加私有
    // 协调核心引用、短期登记候选资源并产生日志或指标。本方法不得创建目标
    // 文件、修改内容或长度、执行追加、建立映射、删除或重建协调目录，也不
    // 得切换全局协调根目录。
    //
    // 如果既有授权对应的协调目录、协议身份或物理根目录已经改变，必须返回
    // 错误；不能以相同路径重新创建一套协调文件并继续使用旧授权，否则会
    // 形成彼此不可见的新旧锁域。
    //
    // # 取消与生命周期
    //
    // 从未轮询的 Future 不得打开文件或登记资源。底层打开前取消不得产生
    // 资源副作用；原生打开或阻塞任务已经提交后，内部完成所有者必须等待其
    // 真实结束。如果最终打开成功但调用方已经取消，完成所有者必须关闭新
    // 句柄、撤销候选资源登记并释放准入租约，不能留下调用方无法取得但仍被
    // 协调器视为活动的幽灵资源。
    //
    // 同步打开和身份核验必须由内部阻塞设施承载，不能阻塞调用方执行器的
    // poll 线程。Future 为 `Send + 'a`，可以在对 namespace 与授权的共享
    // 借用期内跨工作线程迁移；成功的 [`Self::File`] 则拥有全部必要状态并
    // 满足 `'static`。
    //
    // # 幂等性与成本
    //
    // 重复调用不应修改文件内容，但不是严格幂等：每次成功都创建新的逻辑
    // 资源和通常新的原生文件打开，分别增加资源登记和引用计数，也可能独立
    // 失败。它属于冷路径，不承诺零系统调用、零分配或固定延迟；打开完成后
    // 的普通操作不得重复执行完整授权初始化。
    /// 使用既有跨进程授权独立打开一个文件资源。
    ///
    /// 授权已经确定目标位置和实例，因此本方法不再接收定位符。成功前会核验
    /// 目标仍与授权匹配；删除、替换、重建或授权错配返回错误。每次成功调用
    /// 都产生独立逻辑资源，并受所选 [`FileAccessMode`] 限制。
    fn open_with_cross_process_authority<'a>(
        &'a self,
        authority: &'a Self::CrossProcessAuthority,
        access: FileAccessMode,
    ) -> impl Future<Output = pi_result::Result<Self::File>> + Send + 'a;

    // 使用既有跨进程授权排它地移除其绑定的单个文件目标。
    //
    // # 作用与接口层级
    //
    // 本方法是 [`Self::remove_file`] 的跨进程合作式对应入口。它不接收
    // locator，而是从 `authority` 取得已经受管的位置、稳定文件身份、协调
    // 目录代次、目标实例代次和协议版本。这样可以防止调用方把一个文件的
    // 授权与另一个路径拼接，也能保证删除后的旧授权不会静默迁移到同名新
    // 文件。
    //
    // 本方法只移除授权绑定的普通文件名称，不删除目录，不递归，不截断或
    // 覆盖文件内容，也不清理协调目录。授权建立阶段只接受普通文件，因此
    // 提交时若最终条目已经变成符号链接、重解析点、目录、特殊文件或不同
    // 稳定身份，必须按身份分歧处理，不能沿链接或改用其它删除原语。
    //
    // # 参数、借用与安全边界
    //
    // `authority` 只在 Future 的 `'a` 生命周期内共享借用，不被消费。公开
    // 授权值本身不算活动文件资源，不持有阻止删除的共享生命周期租约，也不
    // 永久持有目标文件句柄；因此同一或其它独立建立的授权值仍然存活时可以
    // 执行本方法。成功后这些旧授权可以安全 `Drop`，但任何打开、映射或命名
    // 空间操作都必须因目标实例已经退役而失败。
    //
    // 本方法是安全 Rust interface。不能由安全调用方任意构造的授权已经把
    // 外部合作承诺集中在 [`Self::establish_cross_process_authority`] 或
    // [`Self::create_new_coordinated`] 的 `unsafe` 建立点。实现仍必须核验
    // 授权属于当前 namespace/backend、当前协调根和当前协议实例；类型相同
    // 不能替代运行时核验。调用方若破坏原建立点承诺，安全责任仍追溯到该
    // `unsafe` 调用，不能要求本方法控制绕过协议的原生句柄或进程。
    //
    // # 活动资源与非阻塞排它准入
    //
    // 删除要求所有合作进程中不存在该目标实例的活动文件资源、只读或可写
    // MMAP、候选打开、待建立映射、读取、追加、刷新、截断、覆盖、其它命名
    // 空间变更，以及取消后仍在收尾的拥有型完成者。资源即使暂时空闲也构成
    // 活动所有者；只读映射的任一零成本克隆仍在时同样构成冲突。
    //
    // 当前进程通过授权的私有协调核心检查聚合活动计数，其它合作进程通过
    // 共享生命周期租约被排它租约排除。公开授权数量不参与活动计数。任何
    // 冲突都必须在目标副作用前立即返回，不排队等待资源 `Drop`，也不自动
    // 关闭调用方资源。
    //
    // 内置本地 adapter 必须按以下顺序进入删除：
    //
    // 1. 取得按父目录稳定身份和最终名称识别的进程内父条目拥有型许可；
    // 2. 非阻塞尝试取得同一条目的跨进程父条目/bootstrap 排它门禁；
    // 3. 在私有目标核心中非阻塞登记进程内删除许可并证明活动计数为零；
    // 4. 非阻塞尝试取得跨进程目标生命周期排它租约；
    // 5. 重新核验根目录、协议、父目录、位置、实例代次和目标稳定身份；
    // 6. 推进协议和底层删除；
    // 7. 按相反顺序释放全部许可。
    //
    // 禁止反向获取、原地升级共享锁或在已经取得跨进程门禁后等待后续门禁。
    // 进程内同步临界区只允许状态、计数和拥有型许可转移；其中禁止文件 I/O、
    // `.await`、系统文件锁、用户回调、可能阻塞的日志和无界分配。拥有型许可
    // 可以跨异步阶段存活，但其内部互斥锁 guard 必须在离开短临界区前释放。
    //
    // # 协议状态、提交点与状态幂等性
    //
    // 对授权绑定的同一个 `generation + target_incarnation`，本方法按以下
    // 状态处理：
    //
    // - `Published` 且目标稳定身份完全匹配：原子发布 `Removing`，执行底层
    //   名称移除，再原子发布 `Removed`；
    // - `Removing`：恢复已经不可撤销提交的删除；旧身份仍存在时继续移除，
    //   目标缺失时直接发布 `Removed`；
    // - `Removed` 且受管位置仍为空：幂等返回成功；
    // - `IdentityConflict`：保持隔离并返回错误；
    // - 当前记录已经属于新的目标实例：拒绝旧授权，不访问新文件。
    //
    // `Removing` 的原子发布是不可撤销逻辑提交点。发布之前取消或失败不得
    // 删除目标；发布之后不能回退到 `Published`。本方法的幂等性只覆盖授权
    // 精确绑定的目标实例，不是“相同路径不存在即成功”：缺少合法协议记录、
    // 协调目录被替换或 `Removed` 位置出现旁路对象都必须失败。
    //
    // 在 `Published` 下发现目标缺失或身份不同，必须在不删除当前对象的前提
    // 下发布 `IdentityConflict`，分别记录 `Missing` 或
    // `DifferentIdentity`。在 `Removing` 下发现不同稳定身份也必须隔离，
    // 绝不能删除该新对象或把旧授权迁移给它。只有 `Removing` 下的目标缺失
    // 才是可以直接收口为 `Removed` 的正常恢复状态。
    //
    // # 删除结果、硬链接与物理存续
    //
    // `Ok(())` 表示授权绑定的名称已经由本协议移除，或者协议已经证明同一
    // 实例处于合法 `Removed` 且受管位置仍为空。成功会把当前进程中该实例的
    // 协调核心全局标记为已退役；并发或后续使用任何旧授权都必须失败。
    //
    // 普通文件可能有其它硬链接。删除只解除授权绑定 locator 的名称，不删除
    // 其它名称，也不证明底层字节已经物理销毁或空间已经回收。所有合作进程
    // 的受管资源已经由生命周期租约排除，但 Unix 外部描述符、Windows 不同
    // 共享模式句柄、远端保留版本或不合作参与者仍可能延长底层对象存续。
    // 本库不得为了制造“立即销毁”外观而截断文件、修改 ACL、关闭外部句柄或
    // 删除其它硬链接。
    //
    // 协调目录、不可变协议记录和旧目标实例历史不会随成功或授权 `Drop`
    // 删除。它们用于拒绝旧授权、恢复进程崩溃和防止 ABA；只有以后单独设计
    // 的离线垃圾回收流程才能在证明无活动参与者后处理历史状态。
    //
    // # 错误与移除提交证据
    //
    // 普通失败通过 [`RemoveFailure`] 返回。资源冲突、授权错配、协议不兼容、
    // `Published` 下的目标缺失或身份变化、对象种类错误、权限不足，以及其它
    // 未跨过 `Removing` 提交点的失败使用
    // [`crate::RemoveTargetEvidence::NotRemovedByOperation`]。
    //
    // `Removing` 已经提交后，底层明确没有移除目标的失败可以保留该状态供
    // 显式恢复，并按实际提交事实报告 `NotRemovedByOperation`；底层已经明确
    // 移除名称但 `Removed` 发布或结果交付失败时使用
    // [`crate::RemoveTargetEvidence::RemovedByOperation`]。提交结果确实无法
    // 证明，或者恢复时发现另一稳定身份而无法判断旧目标由哪个执行者移除时，
    // 使用 [`crate::RemoveTargetEvidence::Unknown`]。
    //
    // 失败证据描述该协调式删除意图的提交历史，不是 locator 的实时存在性
    // 查询。实现不得用 `Unknown` 掩盖本可执行的句柄核验，也不得在失败后
    // 自动创建文件、恢复旧绑定或删除身份冲突的新对象。所有可报告条件必须
    // 返回结构化错误，不得 panic。
    //
    // # 取消、恢复与进程崩溃
    //
    // 从未轮询的 Future 不得取得许可、打开目标或改变协议。发布 `Removing`
    // 前取消必须释放已经取得的临时许可且不删除目标。`Removing` 发布后，
    // Future Drop 只表示调用方停止等待；当前进程的拥有型完成者必须继续到
    // `Removed`、`IdentityConflict` 或完整且可再次恢复的 `Removing` 状态。
    //
    // 原生删除、状态发布或阻塞任务一旦提交便不能通过丢弃 Future 假装撤销。
    // 完成者必须拥有所需定位信息、原生句柄和许可，不能在 Future 销毁后访问
    // `authority` 的借用。整个进程退出后，仍持匹配旧授权的其它合作进程可以
    // 再次调用本方法；所有内存授权均已消失时，必须显式调用
    // [`Self::resume_coordinated_file_removal`]，其它 API 不得隐式删除目标。
    //
    // # 线程、运行时、副作用与成本
    //
    // 返回 Future 为 `Send + 'a`，可在 namespace 与授权的共享借用期内跨
    // 工作线程迁移，不要求具体异步运行时，也不承诺 `Sync` 或 `'static`。
    // 同步文件锁、协议文件操作、身份查询和本地删除必须由 adapter 的有界
    // 阻塞设施承载，不能直接长期阻塞执行器 poll 线程。
    //
    // 本方法会读取和原子发布协调记录、打开父目录与临时目标句柄、取得系统
    // 文件锁、更新进程内许可状态、移除 namespace 绑定并可能记录日志或指标，
    // 因此不是纯函数。它不调用用户回调，也不允许在内部临界区重入公开 API。
    //
    // 本地冷路径通常承担 `O(P)` 的受管位置和父目录解析、常数次协议记录及
    // 文件锁操作、一次稳定身份核验、期望 `O(1)` 的私有核心准入和一次删除
    // 系统调用；`P` 是路径长度或组件数。它不扫描进程全局资源或全部历史
    // MMAP 范围。普通读取、追加和已建立映射的字节访问不承担这些成本。
    //
    // 成功不隐式强制同步父目录、卷或协议记录到持久介质，不保证掉电、操作
    // 系统崩溃、失信硬件缓存或硬件损坏后的最新状态。内置首版支持边界仍限于
    // 已证明具备所需稳定身份、原子发布和文件锁语义的 Windows、Linux 本地
    // 普通文件与 Linux tmpfs；能力不足的远端或特殊文件系统必须在提交前返回
    // `Unsupported`，除非 adapter 提供语义等价的持久协调协议。
    /// 使用既有跨进程授权排它移除其绑定的文件名称。
    ///
    /// 任何合作进程仍持有活动资源、映射或冲突操作时立即失败，不等待其结束。
    /// 授权错配、目标被替换或协议状态不允许删除时也在提交前失败。成功表示
    /// 名称移除已提交，不保证立即物理回收或持久化；[`RemoveFailure`] 保存
    /// 本次协调删除可证明的提交结果。
    fn remove_file_with_cross_process_authority<'a>(
        &'a self,
        authority: &'a Self::CrossProcessAuthority,
    ) -> impl Future<Output = pi_result::RawResult<(), RemoveFailure>>
           + Send
           + 'a;

    // 在没有内存中授权时，显式恢复已经提交的协调式单文件删除。
    //
    // # 作用与接口层级
    //
    // 本方法是进程重启和全部公开授权均已消失后的专用恢复入口。它按 locator
    // 重新发现持久协调目录，只允许把已有的 `Removing` 推进到安全终态，或者
    // 幂等确认合法 `Removed`。它绝不能从 `Published` 发起新删除，不建立或
    // 返回授权，不打开可交付的文件资源，也不用于恢复文件内容。
    //
    // 普通打开、创建、映射和授权建立遇到 `Removing` 时只返回明确错误，不能
    // 隐式调用本方法。仍持有匹配旧授权时应优先使用
    // [`Self::remove_file_with_cross_process_authority`]，由授权避免按 locator
    // 重新发现协议实例。
    //
    // # Safety
    //
    // 调用方必须重新保证，从本 Future 开始轮询到恢复产生的最后一个在途
    // 完成者结束为止：
    //
    // - 所有可能访问、映射、打开、删除、改名或替换目标的相关进程和库实例
    //   都遵守同一版本的协调协议；
    // - 所有合作进程解析到同一个物理协调根和锁域；
    // - 不存在绕过协议的原生句柄、映射、namespace 操作或不受管 adapter；
    // - 不受信任主体不能替换、删除或伪造协调目录、记录和锁文件；
    // - 目标父目录、协调根和底层文件系统满足 adapter 声明的稳定身份、原子
    //   发布和文件锁前置条件。
    //
    // 这些外部事实不能由 locator 或 sidecar 文件独立证明。违反承诺可能使
    // 恢复过程错误判断其它进程的映射和文件长度稳定性，因此本入口是
    // `unsafe fn`。`unsafe` 不表示调用方需要提供裸指针；它集中表达合作式
    // 跨进程协议无法从当前进程内部完全验证的前置条件。
    //
    // # 参数、借用与返回值
    //
    // `locator` 在 Future 的 `'a` 生命周期内共享借用。实现可以在首次推进时
    // 克隆拥有型定位符，把它和协议发现结果交给阻塞任务或取消后的完成所有者；
    // 调用方保留原值。成功只返回 `()`，不返回授权、目标身份或恢复状态枚举。
    // 需要随后创建新文件时必须等待本方法成功，再单独调用协调式创建。
    //
    // Future 为 `Send + 'a`，可以在 namespace 与 locator 的借用期内跨工作
    // 线程迁移。克隆 locator 不能被当成稳定身份证明，任何文件副作用之前
    // 仍须从持久记录、父目录和新打开的临时句柄完成真实核验。
    //
    // # 可接受状态与幂等性
    //
    // 本方法只接受以下状态：
    //
    // - `Removing` 且旧稳定身份仍位于受管位置：继续名称移除并发布
    //   `Removed`；
    // - `Removing` 且位置为空：把已完成的底层删除收口为 `Removed`；
    // - 同一旧实例已经是 `Removed` 且位置仍为空：幂等返回成功。
    //
    // `Published` 必须返回前置状态错误，不能因调用方选择了恢复方法而开始
    // 删除。`IdentityConflict` 保持隔离；`Removing` 下出现不同稳定身份时
    // 必须发布该隔离状态并返回不确定证据，绝不能删除新对象。缺少合法协议
    // 记录不能仅凭路径不存在返回成功。当前记录已发布新的目标实例时也必须
    // 拒绝，不能把旧恢复请求作用于新文件。
    //
    // `Removed` 下发现未经协调的新对象说明账面退役状态与真实 namespace
    // 分叉，必须进入 `IdentityConflict` 并返回错误。由显式协调式创建合法
    // 发布的新 `target_incarnation` 则保持 `Published`，本方法只报告状态不
    // 适用，不修改或隔离该新实例。
    //
    // # 门禁、并发与锁顺序
    //
    // 本方法与协调式删除使用完全相同的门禁方向：进程内父条目许可、跨进程
    // 父条目/bootstrap 排它门禁、进程内删除许可、跨进程目标生命周期排它
    // 租约，最后进行身份与协议核验。除首个进程内拥有型许可可以按 adapter
    // 的异步准入策略建立外，取得跨进程门禁后的后续步骤都只能非阻塞尝试；
    // 活动资源或另一恢复者存在时立即返回冲突。
    //
    // 禁止反向取锁、共享到排它的原地升级、带跨进程门禁等待其它许可，以及
    // 在同步注册表临界区执行 I/O、`.await`、文件锁、用户回调或无界分配。
    // 所有许可失败时按相反顺序释放。目标生命周期排它租约取得成功才证明
    // 所有合作进程当前没有活动资源；公开授权值本身不阻塞恢复。
    //
    // # 错误与删除证据
    //
    // 失败通过 [`RemoveFailure`] 返回。没有协议记录、状态仍为 `Published`、
    // 协议不兼容、权限不足、活动资源冲突以及其它未执行底层移除的失败，按
    // 真实事实使用 [`crate::RemoveTargetEvidence::NotRemovedByOperation`]。
    //
    // 底层删除已经明确完成但终态发布或结果交付失败时使用
    // [`crate::RemoveTargetEvidence::RemovedByOperation`]。`Removing` 下出现
    // 不同稳定身份时，旧删除可能已由崩溃前执行者完成，必须使用
    // [`crate::RemoveTargetEvidence::Unknown`]。证据描述同一持久删除意图的
    // 可证明历史，不是 locator 当前存在性的独立快照。
    //
    // 可报告的 locator、协议、身份、锁、权限、资源和 I/O 错误不得 panic。
    // 实现不得自动删除身份冲突对象、回退 `Removing`、伪造协调记录或为了
    // 继续恢复而修改目标权限和 ACL。
    //
    // # 取消、进程崩溃与资源收尾
    //
    // 从未轮询的 Future 不得打开目录、取得文件锁或修改记录。由于删除意图
    // 在调用前已经是 `Removing`，取得门禁前取消可以直接停止并把持久状态
    // 留给以后恢复。原生删除、记录发布或阻塞任务一旦提交，Future Drop 只
    // 表示停止等待；拥有型完成者必须继续到安全停止点并释放全部许可。
    //
    // 如果整个进程再次退出，持久状态仍是后续恢复依据；本方法不承诺抵御
    // 掉电或操作系统崩溃导致的未持久化状态回退。取消没有错误返回通道，
    // 调用方需要确认结果时可以在合作条件仍成立后安全重试本方法。
    //
    // # 副作用、性能与支持边界
    //
    // 本方法会读取并可能发布协调记录、打开父目录和临时目标句柄、取得系统
    // 文件锁、更新进程内恢复许可、移除 namespace 绑定并记录日志或指标，
    // 因而不是纯函数。它不调用用户代码，不返回文件资源，也不清理协调目录。
    //
    // 本地成本通常为 `O(P)` 的定位符和父目录解析、常数次协议与文件锁操作、
    // 一次身份核验、期望 `O(1)` 的进程内准入和至多一次底层删除；它是异常
    // 恢复冷路径，不进入普通文件 I/O 或 MMAP 字节访问热路径。同步工作必须
    // 由有界阻塞设施承载，不能长期阻塞异步执行器 poll 线程。
    //
    // 标准内置实现只对已证明支持所需能力的 Windows、Linux 本地普通文件和
    // Linux tmpfs 提供该协议。远端或特殊文件系统只有在 adapter 提供语义
    // 等价的持久状态机、稳定身份和排它租约时才能实现；否则必须返回
    // `Unsupported`，不能用进程内互斥锁冒充跨进程恢复。
    /// 在没有内存授权时恢复已经提交的协调式文件删除。
    ///
    /// 本方法只允许推进先前已经进入删除状态的同一目标实例，或确认其已删除；
    /// 不会从正常可用状态发起一次新删除，也不会删除同名重建对象。失败通过
    /// [`RemoveFailure`] 报告可证明的历史状态。
    ///
    /// # Safety
    ///
    /// 调用方必须保证所有相关进程遵守同一协调协议，并保证协调记录可信且与
    /// `locator` 所属目标实例对应。同一物理目标还必须始终通过相同的物理
    /// 父目录和原生末级文件名参与协议；不得从另一硬链接名恢复删除。违反
    /// 这些前提可能使恢复判断失真。
    unsafe fn resume_coordinated_file_removal<'a>(
        &'a self,
        locator: &'a Self::Locator,
    ) -> impl Future<Output = pi_result::RawResult<(), RemoveFailure>>
           + Send
           + 'a;
}