pi_async_fs 0.1.2

//! 已打开文件对象的运行时无关数据 I/O 合同。
//!
//! [`FileIo`] 与 [`crate::FileNamespace`] 的路径管理职责分离：namespace 负责
//! 解析位置并独立打开资源，本 trait 只操作已经绑定到具体本地文件或远端
//! 对象的活动资源。各方法分别声明访问角色、buffer、失败恢复、取消和并发
//! 边界，不要求调用方使用某个具体异步运行时。

use core::future::Future;

use crate::{
    BufferFailure, DetachableWriteBuffer, FileFlushMode, GrowableReadBuffer,
    MmapRange, OverwriteFailure, ReadGrowthLimit, ReadGrowthOutcome,
    ReadMmapHandle, ReadTargetRegion, ReadWriteMmapHandle,
};

// 已打开文件对象的数据 I/O 能力。
//
// # 线程与所有权
//
// `Send` 允许不可克隆资源整体移动到其它线程；`Sync` 允许共享借用并发执行
// 后续明确声明为无共享游标的只读操作。它们只保证 Rust 内存安全，不证明
// 文件内容快照、操作原子性、追加记录完整性或持久化顺序。
//
// 顺序读取、严格追加和其它独占操作按各自合同使用 `&mut self`。调用方不能
// 通过共享引用绕过这种独占要求；映射内容的修改则通过独立的可写映射句柄
// 完成，不借用文件顺序游标。
//
// 公开映射句柄是不透明的拥有型资源。调用方只能经过句柄明确提供的方法
// 读取、修改和刷新映射；不能取得裸地址、可分离的底层映射对象或比句柄
// 借用活得更久的视图。
//
// 本版不提供共享游标的顺序写入能力。尾部追加是独立的打开模式和操作
// 模型，绝不得用“定位到尾部后顺序写入”仿冒。如果未来引入顺序写入，
// 它必须与同一稳定文件身份上的追加写入自动互斥，不得同时执行。
//
// # 不可克隆资源合同
//
// 本 trait 不继承 `Clone`，内置公开文件资源也不会实现 `Clone`。Rust 不能
// 对普通泛型参数声明否定的 `!Clone` bound，因此第三方实现必须自行遵守：
// 不得通过克隆公开资源产生共享同一底层文件句柄的第二个写入或追加通道。
// 多个资源需要操作同一文件时，必须分别通过 namespace 独立打开，并由进程
// 内稳定文件身份协调器汇合冲突状态。
//
// # 生命周期与异步运行时
//
// trait 本身不要求 `'static`，使受控作用域包装仍可实现它；
// [`crate::FileNamespace::File`] 额外要求 `'static`。后续每个方法返回标准
// `Future + Send`，不绑定具体运行时，也不保证已经开始轮询的后端操作可以在
// 任意两个运行时之间迁移。
//
// # 当前能力范围
//
// 当前内容写入面保留三种能力：独立打开资源的
// 严格尾部追加、全文件原地覆盖，以及通过可写映射句柄修改其已获准映射
// 范围。本版明确不提供顺序写入、任意偏移随机写入或“先定位再写入”接口。
// 覆盖不是由调用方拼接的“先截断、再追加”，而是一个不可与冲突操作交错的
// 独立方法。普通文件强刷新已经作为独立完成屏障声明；它不替代可写映射句柄
// 自己的映射页刷新。
//
// 严格追加可以与已建立映射及其句柄方法并发，不会扩大既有映射的
// 范围快照。“建立新映射”与“正在执行追加”必须按稳定文件身份短暂
// 串行，以便原子地确认长度快照和预留不重叠范围；这不会使已存活的映射
// 失效。同一稳定文件身份的多个追加调用也必须以完整公开调用为单位
// 串行执行。
//
// 全文件覆盖与同一稳定文件身份的普通读取、追加、截断、其它覆盖、任何
// 活动或待建立映射，以及安全删除和以后可能加入的替换互斥。默认 `rename`
// 不取得内容租约；平台因占用状态拒绝改名时直接返回明确错误。不同文件的
// 只读映射可以作为覆盖输入；目标文件自身的映射及其派生视图必须在任何
// 副作用之前拒绝。
/// 已打开文件资源的运行时无关数据 I/O 接口。
///
/// `Send + Sync` 允许资源在线程间移动和共享，但顺序读取、追加、覆盖、截断
/// 与刷新仍通过 `&mut self` 保持单资源独占。定位读取和映射建立使用共享借用，
/// 其实际并发边界由各方法声明。所有异步方法返回标准 `Future + Send`，不绑定
/// 具体异步运行时。
///
/// 公开文件资源不应被克隆；同一文件需要多个操作通道时必须通过 namespace
/// 独立打开。当前写入面仅包括严格尾部追加、全文件覆盖、缩短文件，以及通过
/// 可写映射句柄修改获准范围；不提供顺序写入或任意偏移普通写入。
///
/// 可报告的输入、访问模式、能力、冲突和 I/O 失败均通过返回值表达，不得
/// panic。从未轮询的 Future 不产生文件副作用；操作已经不可撤销地提交后，
/// 取消不等于回滚。接口不调用用户代码，也不承诺固定延迟、零分配、零复制
/// 或持久化；需要持久化屏障时必须显式刷新。
///
/// # 同一文件的并发边界
///
/// 并发规则按底层文件身份生效，即使操作来自不同定位符、不同独立资源或不同
/// 线程。任意活动映射与普通随机/顺序读取、覆盖、截断、安全
/// 删除以及新建相交映射互斥；同一文件只允许多个逻辑范围完全不相交的映射。
/// 严格尾部追加是唯一可以与既有映射长期并存的普通内容 I/O，但正在执行追加
/// 时不能建立新映射。同一文件的多个追加调用完整串行，字节不得交错。
/// 普通文件刷新可与只读/可写映射及独立资源追加并存，只与覆盖、截断等
/// 全文件破坏性操作互斥；映射写后也允许请求普通文件刷新。
///
/// 默认 namespace 改名不参加内容操作互斥，是否允许由平台和文件系统决定。
/// 普通资源只协调当前进程内共享同一库状态的操作；跨进程保证只适用于通过
/// 显式跨进程授权打开的资源。
///
/// 所有方法都会观察外部文件状态，读取还会修改目标缓冲区，写入、截断、
/// 映射和刷新会产生文件或资源副作用，因此都不是纯函数。只读查询和读取
/// 可以重复调用，但并不保证外部状态不变或结果相同；追加、覆盖和截断不得
/// 默认视为幂等。传输数据的工作量至少随实际处理字节数增长，映射与刷新还
/// 可能随目标范围和脏页数量增长；任何异步方法都可能分配操作状态并等待
/// 不确定时长的存储 I/O，但不会调用用户代码。
pub trait FileIo: Send + Sync {
    // 查询当前文件或远端对象的内容字节长度快照。
    //
    // # 返回值与并发变化
    //
    // 成功值是后端在本次调用执行期间观察到的 `u64` 字节长度；零明确表示
    // 当时观察到空内容。它不是锁、版本令牌或未来读取保证，并发追加、截断、
    // 替换或远端一致性延迟可以使该值在返回后立即过期。
    //
    // 实现不得用未声明时效的缓存冒充当前查询。活动 MMAP 不阻止本方法；
    // 映射建立后的追加可能使本方法返回大于映射冻结快照的新长度，但不会
    // 扩大任何既有映射范围。
    //
    // # 错误、取消与副作用
    //
    // 所有可报告失败进入 [`pi_result::Error`]，本方法不得 panic。它不修改
    // 文件内容，重复调用安全但结果不保证相同；实现仍可能执行元信息系统
    // 调用、远端请求、日志或指标，因此不是纯函数。丢弃 Future 后不得产生
    // 文件内容副作用；后端已经开始的只读查询是否继续完成由 adapter 的取消
    // 合同说明。
    //
    // # 线程与成本
    //
    // 共享借用允许与其它明确可并发的只读操作同时调用。Future 为 `Send`，
    // 可在调用借用期内跨工作线程迁移。本地通常需要 O(1) 元信息系统调用，
    // 远端通常至少需要一次请求；接口不承诺无阻塞、固定延迟或无分配。
    /// 返回当前可观察到的内容字节长度快照。
    ///
    /// 该值不是版本、锁或后续读取保证，并发追加或外部修改可能使其立即过期。
    /// 本方法不修改文件内容；活动映射不会阻止查询，映射建立后的追加也不会
    /// 扩大既有映射视图。
    fn byte_len(
        &self,
    ) -> impl Future<Output = pi_result::Result<u64>> + Send + '_;

    // 从绝对文件偏移处读取至调用方缓冲区的指定窗口。
    //
    // 本方法用于不依赖共享顺序游标的随机读取（positional read）。`offset`
    // 是源文件或远端对象中的零起始字节偏移；`buffer` 是调用方独占借用的
    // 已初始化可写字节存储；`target` 只描述本次允许覆盖
    // `buffer.as_mut()` 中的哪一段连续窗口。参数顺序固定为“源位置、目标
    // 存储、目标窗口”，使文件范围与内存范围不会混淆。
    //
    // # 目标窗口与边界检查
    //
    // 实现必须在发起底层 I/O 前验证 `target` 完整落在调用本方法时取得的
    // `buffer.as_mut()` 视图内，并验证 `offset + target.len()` 不发生 `u64`
    // 溢出。任何无效窗口或算术溢出都返回 [`pi_result::Error`]，不得访问
    // 后端，且不得修改缓冲区。
    //
    // 空窗口成功返回 `0`，不得访问后端。`offset` 位于当时观察到的文件尾
    // 或其后时同样成功返回 `0`。本接口只接受已经初始化且可由安全 Rust
    // 写入的 `[u8]` 视图；未初始化备用容量不属于 `AsMut<[u8]>` 暴露的合法
    // 区域，增长型读取由单独接口负责。
    //
    // # 成功、短读与文件尾
    //
    // 成功值 `n` 满足 `n <= target.len()`。实现只可覆盖目标窗口起点开始的
    // 前 `n` 个字节；窗口剩余部分及窗口外字节必须保持不变。正数短读是
    // 合法结果，并不单独证明已经到达文件尾：信号中断、后端分块、远端
    // 响应边界等都可能产生短读。需要填满整个窗口的调用方应使用后续的
    // 精确读取接口，而不是假设一次 `read_at` 足够。
    //
    // # 错误、局部修改与取消
    //
    // 读取失败只返回 [`pi_result::Error`]，不会返回缓冲区或进度载体。若错误
    // 发生前底层操作已经提交部分字节，则调用方必须把整个目标窗口视为
    // “内容可能已被部分修改”；接口不承诺回滚，也不通过错误值报告可靠的
    // 已完成字节数。窗口外字节仍必须保持不变。
    //
    // 丢弃返回的 Future 后，实现不得再访问或修改 `buffer`。不能安全取消
    // 借用式系统 I/O 的 adapter 必须在内部使用自有中转缓冲区，并且只在
    // Future 仍存活时把结果提交到调用方窗口。中转策略属于实现细节；本
    // 接口不承诺零复制、单次系统调用或零分配。
    //
    // # 并发、MMAP 与异步运行时
    //
    // 本方法使用共享 `&self` 且不推进共享游标，因此同一资源上的多个定位
    // 读取在 Rust 借用允许时可以并发。它仍受进程内文件身份协调规则约束：
    // 待建立或活动的 MMAP 与随机读取互斥时，adapter 必须在访问内容前返回
    // 明确错误。不同进程造成的替换、截断或映射冲突不由本接口协调。
    //
    // 返回 Future 是 `Send`，可在借用生命周期 `'a` 内跨工作线程迁移；它
    // 不必是 `'static`。`B` 不要求 `Clone`、`Sync`、`'static`、`AsRef` 或
    // `BufMut`，因此 `[u8]`、`Vec<u8>`、`Box<[u8]>`、`BytesMut` 等只要能
    // 通过 `AsMut<[u8]>` 暴露本次可写区域，均可作为缓冲区。若运行时要求
    // 顶层任务为 `Send + 'static`，调用方可在 `async move` 任务中同时拥有
    // 文件资源和缓冲区，再在任务内部借用它们调用本方法。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法修改调用方缓冲区，并可能执行系统调用、远端请求、协调器查询、
    // 日志或指标，因此不是纯函数。对不变的文件快照和相同初始缓冲区重复
    // 调用可得到等价字节，但接口不保证外部文件状态不变，故不提供结果幂等
    // 保证。时间成本至少与实际读取字节数线性相关；空间成本由 adapter 决定。
    /// 从绝对文件偏移读取至已初始化缓冲区的指定窗口。
    ///
    /// 成功值 `n` 不大于窗口长度；只允许修改窗口起点后的前 `n` 字节，短读
    /// 是合法结果。空窗口或从文件尾及其后读取返回零。无效窗口和偏移算术
    /// 溢出必须在修改缓冲区前失败。普通错误可能保留已写入的窗口前缀；返回
    /// 后不得再访问 `buffer`。本方法不使用或推进顺序游标。
    fn read_at<'a, B>(
        &'a self,
        offset: u64,
        buffer: &'a mut B,
        target: ReadTargetRegion,
    ) -> impl Future<Output = pi_result::Result<usize>> + Send + 'a
    where
        B: AsMut<[u8]> + Send + ?Sized + 'a;

    // 从绝对文件偏移处精确填满调用方缓冲区的指定窗口。
    //
    // 本方法是 [`Self::read_at`] 的“全部完成或返回错误”形式。`offset` 是源
    // 文件或远端对象中的零起始字节偏移；`buffer` 是调用方独占借用的已初始
    // 化可写存储；`target` 指定唯一允许覆盖的目标窗口。参数顺序继续固定为
    // “源位置、目标存储、目标窗口”。本方法不使用或推进共享顺序游标。
    //
    // # 成功与文件尾
    //
    // 只有目标窗口中的每一个字节都已由本次读取填入时才返回 `Ok(())`。
    // 正数短读不是成功终止条件；实现必须继续从相应文件偏移读取到窗口剩余
    // 后缀。若窗口尚未填满便明确读到文件尾，必须返回表示意外文件尾的
    // [`pi_result::Error`]。因此返回类型不再携带冗余字节数。
    //
    // 空窗口直接返回 `Ok(())`，不得访问后端；它在任何有效 `offset` 下都已
    // 被精确填满。非空窗口的 `offset` 位于当时观察到的文件尾或其后则返回
    // 意外文件尾错误。并发截断、替换或远端一致性变化可能使一次原本足够长
    // 的资源在操作期间变短，本接口不提供文件快照保证。
    //
    // # 前置验证与目标修改范围
    //
    // 实现必须先把 `target` 绑定到调用时 `buffer.as_mut()` 的已初始化视图，
    // 再以受检转换和受检加法验证完整源范围可以表达；验证成功前不得访问
    // 后端或修改缓冲区。窗口越界、长度转换失败或文件偏移计算溢出均返回
    // [`pi_result::Error`]，并保持整个缓冲区不变。
    //
    // 成功时只可覆盖目标窗口，窗口外字节必须保持不变。本接口不能写入
    // `Vec` 等类型的未初始化备用容量，也不能改变其逻辑长度；这正是固定
    // 长度读取与增长型读取的能力分界。
    //
    // # 错误、部分完成与取消
    //
    // 一旦读取已经开始，后续意外文件尾或其它错误可能发生在目标前缀已经
    // 被覆盖之后。失败只返回 [`pi_result::Error`]，不返回缓冲区或进度；调用
    // 方必须把整个目标窗口视为“可能已被部分修改”。实现不承诺回滚、清零
    // 或恢复旧内容，窗口外字节则仍必须保持不变。
    //
    // 丢弃返回的 Future 后，实现不得继续访问或修改 `buffer`。取消前已经
    // 同步提交的目标前缀可以保留。无法安全取消借用式底层 I/O 的 adapter
    // 必须使用自有中转存储，并等到底层停止访问后再释放；是否选择等到完整
    // 成功才一次提交属于实现优化，不能改变上述允许部分修改的公共合同。
    //
    // # 并发、生命周期与类型约束
    //
    // 本方法使用共享 `&self`，可与其它无共享游标的定位读取并发，但仍受
    // 同一文件的进程内操作协调器约束，并与待建立或活动的 MMAP 互斥。不同
    // 进程的文件修改与映射不在本接口的安全协调范围内。
    //
    // 返回 Future 为 `Send + 'a`。`B` 只需通过 `AsMut<[u8]>` 提供已经初始
    // 化的固定目标，并允许其独占借用随 Future 跨线程迁移；不要求 `Clone`、
    // `Sync`、`'static`、`AsRef<[u8]>`、`BufMut` 或写侧的
    // [`crate::DetachableWriteBuffer`]。运行时要求顶层任务为 `'static` 时，
    // 调用方可以让 `async move` 任务拥有资源与缓冲区，再在任务内部借用。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法修改目标窗口并执行外部 I/O，不是纯函数；重复调用的结果会受
    // 文件并发变化影响，不能视为结果幂等。实现可能通过多次系统调用或远端
    // 请求消化短读，时间成本至少与目标长度线性相关；接口不保证单次调用、
    // 零分配、零复制或固定延迟。可报告的输入、EOF 和后端失败不得 panic。
    /// 从绝对文件偏移精确填满已初始化缓冲区的指定窗口。
    ///
    /// 空窗口直接成功；非空窗口在填满前到达文件尾返回错误。普通错误可能
    /// 保留已写入的窗口前缀，但窗口外字节不得改变。无效窗口或算术溢出在
    /// I/O 前失败。本方法不使用或推进顺序游标。
    fn read_exact_at<'a, B>(
        &'a self,
        offset: u64,
        buffer: &'a mut B,
        target: ReadTargetRegion,
    ) -> impl Future<Output = pi_result::Result<()>> + Send + 'a
    where
        B: AsMut<[u8]> + Send + ?Sized + 'a;

    // 从绝对文件偏移处读取，并把新字节追加到增长型缓冲区逻辑尾部。
    //
    // 本方法用于“从指定源位置朝文件尾读取，但以调用方明确的资源上限为
    // 边界”的定位增长读取。`offset` 是源文件或远端对象中的零起始字节
    // 偏移；`buffer` 是调用方独占借用的增长型承载体；`limit` 只限制本次
    // 调用最多新增的有效字节数。参数顺序固定为“源位置、目标承载体、增长
    // 上限”。本方法不读取或推进共享顺序游标。
    //
    // # 追加而非覆盖
    //
    // 假设调用开始时 [`AsRef::<[u8]>::as_ref`] 暴露的已初始化逻辑内容为
    // `[0, L)`。本方法必须逐字节保留该前缀，只把新读取且确认初始化的字节
    // 追加到逻辑尾部。它没有 [`ReadTargetRegion`] 参数，也绝不覆盖旧内容；
    // 需要替换语义的调用方应先显式清空承载体，或使用新的空承载体。
    //
    // 实现应优先使用现有备用容量，并在空间不足时按具体缓冲区合同自动扩容。
    // 未初始化备用容量不是公开字节：只有后端确认写完的连续前缀才能通过
    // [`bytes::BufMut::advance_mut`] 提交并进入 `AsRef<[u8]>` 的有效视图。
    // 实现可以取得超过本次需要的物理容量，但不得读取或提交超过 `limit` 的
    // 字节。
    //
    // # 成功终止分类
    //
    // 成功返回 [`ReadGrowthOutcome`]，其字节数只统计本次新增并已提交的后缀：
    //
    // - 在用尽上限前明确观察到文件尾，返回
    //   [`ReadGrowthOutcome::EndOfFile`]；
    // - 恰好提交上限允许的字节数，返回
    //   [`ReadGrowthOutcome::LimitReached`]，不得为了区分“文件恰好到此结束”
    //   再执行一次探测读取。
    //
    // `limit == 0` 时必须零 I/O、零分配、零修改地返回
    // `LimitReached { appended_bytes: 0 }`。它只表示调用方没有授予探测权限，
    // 不能解释为文件为空或已经到达文件尾。上限大于零且第一次有效读取便
    // 观察到 EOF 时，返回 `EndOfFile { appended_bytes: 0 }`。
    //
    // # 前置验证、错误与部分追加
    //
    // 实现必须在 I/O 前将 `limit` 绑定到调用时的逻辑长度，验证最终长度、
    // 文件偏移转换及 `offset + maximum_additional_bytes` 均可表达。任何前置
    // 验证错误必须保持缓冲区和后端状态不变。
    //
    // 读取开始后的错误只返回 [`pi_result::Error`]，不返回缓冲区、
    // [`ReadGrowthOutcome`] 或其它进度。错误发生前已经安全提交的后缀保留，
    // 不回滚；调用方在 Future 结束后仍通过原 `&mut B` 的借用恢复访问。旧
    // 前缀必须保持不变，未初始化字节不得进入公开逻辑长度。可报告的容量
    // 算术、协议和后端错误不得 panic；全局分配器终止进程等行为不属于本
    // 接口可恢复错误保证。
    //
    // # 取消与完成式 I/O
    //
    // 丢弃 Future 后，实现不得继续访问调用方 `buffer`。取消前已经同步提交
    // 的完整后缀可以保留。completion adapter 不得把 `chunk_mut()` 借出的
    // 地址交给可能越过 poll 或 Future 生命周期的底层操作；它必须使用自有
    // owned 中转存储，等后端停止访问后，再把确认完成的连续字节复制并提交
    // 到调用方承载体。
    //
    // # 并发、生命周期与类型范围
    //
    // 本方法使用共享 `&self` 且不推进共享游标，可与其它定位读取并发，但
    // 仍受同一文件进程内协调规则约束，并与待建立或活动的 MMAP 互斥。不同
    // 进程造成的修改、截断和映射冲突不在本接口协调范围内。
    //
    // 返回 Future 为 `Send + 'a`。`B` 必须满足 [`GrowableReadBuffer`] 的
    // “完整初始化视图 + 未初始化尾部提交”关系，并且能够随独占借用跨线程
    // 迁移；不要求 `Clone`、`Sync`、`'static` 或写侧的
    // [`crate::DetachableWriteBuffer`]。首批内置类型是 `Vec<u8>` 与
    // [`bytes::BytesMut`]；只读引用、固定切片、`Box<[u8]>`、`Arc<[u8]>` 和
    // `Cow<'_, [u8]>` 不具备本接口所需的增长能力。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法增长调用方缓冲区并执行外部 I/O，不是纯函数，也不是可在同一
    // 缓冲区上无变化重复执行的幂等操作。时间成本至少与新增字节数线性相关；
    // 扩容和 completion 中转可能产生 O(n) 复制与额外内存。接口不承诺零
    // 复制、零分配、单次系统调用、固定延迟或文件内容快照。
    /// 从绝对文件偏移读取，并把字节追加到增长型缓冲区的逻辑尾部。
    ///
    /// 本次最多新增 `limit` 允许的字节。成功通过 [`ReadGrowthOutcome`] 区分
    /// 在限额内观察到文件尾，或已精确用尽限额而未额外探测文件尾。零限额
    /// 不执行 I/O。错误前已经提交的后缀保留；返回或取消完成后不得再访问
    /// `buffer`。本方法不推进顺序游标。
    fn read_to_end_at<'a, B>(
        &'a self,
        offset: u64,
        buffer: &'a mut B,
        limit: ReadGrowthLimit,
    ) -> impl Future<Output = pi_result::Result<ReadGrowthOutcome>> + Send + 'a
    where
        B: GrowableReadBuffer + Send + 'a;

    // 从当前逻辑游标读取至调用方缓冲区的指定窗口。
    //
    // 本方法是 [`Self::read_at`] 的顺序游标形式。它从调用开始时的公开逻辑
    // 游标 `C` 读取，而不是由调用方提供绝对文件偏移。`buffer` 是调用方
    // 独占借用的已初始化可写存储，`target` 指定本次唯一允许覆盖的连续窗口。
    // 参数顺序固定为“目标存储、目标窗口”。
    //
    // 使用 `&mut self` 是接口的并发控制，而不仅是实现细节：一次顺序操作
    // 在 Future 完成或被丢弃前独占该文件资源，从类型层消除同一游标上两个
    // 操作的先后次序竞态。需要并发读取的调用方应使用不推进游标的定位读取，
    // 或通过 namespace 分别打开具有独立逻辑游标的资源。
    //
    // # 成功、短读与游标提交
    //
    // 成功值 `n` 满足 `n <= target.len()`。本方法读取源范围 `[C, C + n)`，
    // 只覆盖目标窗口起点开始的前 `n` 个字节，并在返回成功时把公开逻辑
    // 游标精确提交为 `C + n`。窗口剩余部分和窗口外字节保持不变。
    //
    // 正数短读是合法成功结果，不单独证明 EOF。读取在当时观察到的文件尾
    // 返回 `Ok(0)`，游标保持 `C`。外部进程或其它独立资源可以并发改变文件
    // 内容与长度，本方法不承诺数据快照或后续读取仍观察同一个版本。
    //
    // # 空窗口与前置验证
    //
    // 空目标窗口必须零 I/O 地返回 `Ok(0)`，并保持游标不变。实现必须在
    // 访问后端前把 `target` 绑定到 `buffer.as_mut()` 的已初始化视图，并以
    // 受检转换及受检加法验证最大源偏移。窗口越界、长度无法表达或
    // `C + target.len()` 溢出均返回 [`pi_result::Error`]，且缓冲区、游标和
    // 后端状态保持不变。
    //
    // 固定读取不得访问 `Vec` 等类型的未初始化备用容量，也不得改变承载体
    // 逻辑长度。需要保留旧内容并自动扩容的调用方应使用增长型顺序读取。
    //
    // # 错误、取消与强游标保证
    //
    // 读取开始后的普通错误可能发生在目标窗口前缀已经被修改之后。错误只
    // 返回 [`pi_result::Error`]，不返回缓冲区或进度；调用方必须把整个目标
    // 窗口视为“可能已被部分修改”，实现不承诺回滚。窗口外字节必须保持
    // 不变。
    //
    // 与缓冲区的允许部分修改不同，公开逻辑游标具有事务式提交保证：只有
    // 返回 `Ok(n)` 才推进 `n`；任何普通错误或 Future 取消都必须保持调用前
    // 的 `C`。adapter 因而不得直接把可能在失败或取消后继续推进的操作系统
    // 共享文件指针冒充公开游标。它可以维护独立逻辑游标，并使用定位 I/O、
    // 可证明的游标恢复流程或等价机制实现该合同。
    //
    // 丢弃 Future 后实现不得继续访问或修改 `buffer`。不能安全取消的
    // completion 操作必须使用自有中转存储，并在底层确认停止访问后释放；
    // 取消前已经提交到目标窗口的字节可以保留，但不能据此推进公开游标。
    //
    // # 并发、MMAP 与生命周期
    //
    // `&mut self` 将同一资源的顺序读取、游标变更和关闭自然串行。本版
    // 不提供顺序写入；追加由独立打开的追加资源执行。不同独立打开资源
    // 拥有不同游标，但其内容操作仍通过进程内
    // 稳定文件身份协调器执行冲突检查。本方法与同一文件待建立或活动的
    // MMAP 互斥；跨进程修改与映射不在本接口协调范围内。
    //
    // 返回 Future 为 `Send + 'a`。`B` 只需通过 `AsMut<[u8]>` 暴露已初始化
    // 固定目标，并能够随独占借用跨线程迁移；不要求 `Clone`、`Sync`、
    // `'static`、`AsRef<[u8]>`、`BufMut`、[`GrowableReadBuffer`] 或写侧的
    // [`crate::DetachableWriteBuffer`]。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法修改目标窗口、成功时推进逻辑游标并执行外部 I/O，因此不是纯
    // 函数，也不是可无条件重复的幂等操作。时间成本至少与实际读取字节数
    // 线性相关；adapter 的中转与游标管理可能分配和复制。接口不承诺零复制、
    // 零分配、单次系统调用、固定延迟或底层原生共享游标。
    /// 从当前逻辑游标读取至已初始化缓冲区的指定窗口。
    ///
    /// 成功值 `n` 不大于窗口长度，并将逻辑游标一次推进 `n`；短读合法，空
    /// 窗口和文件尾返回零且不推进。普通错误或取消必须保持调用前游标，尽管
    /// 缓冲区窗口前缀可能已经改变。无效窗口和算术溢出在 I/O 前失败。
    fn read<'a, B>(
        &'a mut self,
        buffer: &'a mut B,
        target: ReadTargetRegion,
    ) -> impl Future<Output = pi_result::Result<usize>> + Send + 'a
    where
        B: AsMut<[u8]> + Send + ?Sized + 'a;

    // 从当前逻辑游标精确填满调用方缓冲区的指定窗口。
    //
    // 本方法结合 [`Self::read_exact_at`] 的完整填充语义与 [`Self::read`] 的
    // 独占顺序游标语义。它从调用开始时的公开逻辑游标 `C` 读取；`buffer`
    // 是调用方独占借用的已初始化可写存储；`target` 是本次唯一允许覆盖的
    // 连续窗口。参数顺序固定为“目标存储、目标窗口”。
    //
    // # 成功与一次性游标提交
    //
    // 只有目标窗口中的每一个字节都已由本次操作填入时才返回 `Ok(())`。
    // 实现必须在内部消化任意正数短读；短读不是成功终止条件。完整成功后，
    // 公开逻辑游标从 `C` 一次性提交为 `C + target.len()`。返回类型不携带
    // 字节数，因为成功完成量由已解析目标窗口唯一确定。
    //
    // 空目标窗口零 I/O 返回 `Ok(())`，游标保持 `C`。非空窗口在填满前
    // 明确观察到文件尾时，返回表示意外文件尾的 [`pi_result::Error`]。外部
    // 文件变化可能导致操作期间出现意外 EOF；本接口不承诺内容快照。
    //
    // # 前置验证与修改范围
    //
    // 实现必须先把 `target` 绑定到调用时 `buffer.as_mut()` 的已初始化视图，
    // 再以受检转换及受检加法验证完整源范围 `[C, C + target.len())` 可以
    // 表达。窗口越界、长度转换失败或文件偏移溢出均必须在后端 I/O 前返回
    // 错误，并保持缓冲区、游标和后端状态不变。
    //
    // 成功时只可覆盖目标窗口，窗口外字节保持不变。固定读取不得访问未初始
    // 化备用容量或改变承载体逻辑长度；增长语义由独立接口提供。
    //
    // # 错误、意外 EOF 与取消
    //
    // 操作开始后的错误或意外 EOF 可能发生在目标窗口前缀已经被覆盖之后。
    // 失败只返回 [`pi_result::Error`]，不返回缓冲区或进度；调用方必须把整个
    // 目标窗口视为“可能已被部分修改”。实现不承诺恢复旧字节，窗口外仍
    // 必须保持不变。
    //
    // 公开逻辑游标具有整次操作的事务式提交保证：只有完整成功才一次推进
    // 目标窗口长度；普通错误、意外 EOF 或 Future 取消都保持调用前的 `C`。
    // 因此 adapter 不能通过反复调用会逐次提交游标的公开 [`Self::read`] 来
    // 实现本方法，除非它另有可靠的游标恢复机制。推荐使用定位 I/O 和一个
    // 尚未公开提交的内部候选游标，完成后再更新公开状态。
    //
    // 丢弃 Future 后实现不得继续访问或修改 `buffer`。不能安全取消的
    // completion 操作必须使用自有中转存储，并等到底层确认停止访问。取消
    // 前已经提交到目标窗口的字节可以保留，但不能推进公开逻辑游标。
    //
    // # 并发、生命周期与类型范围
    //
    // `&mut self` 使同一资源的顺序读取、游标变更和关闭自然串行。本版
    // 不提供顺序写入；追加由独立打开的追加资源执行。不同独立打开资源具有
    // 独立游标，但仍通过进程内稳定文件身份协调器处理
    // 内容操作冲突。本方法与同一文件待建立或活动的 MMAP 互斥；跨进程变化
    // 不在本接口协调范围内。
    //
    // 返回 Future 为 `Send + 'a`。`B` 只需通过 `AsMut<[u8]>` 暴露固定的
    // 已初始化目标，并允许独占借用跨线程迁移；不要求 `Clone`、`Sync`、
    // `'static`、`AsRef<[u8]>`、`BufMut`、[`GrowableReadBuffer`] 或写侧的
    // [`crate::DetachableWriteBuffer`]。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法修改目标窗口、成功时推进逻辑游标并执行外部 I/O，不是纯函数，
    // 也不是无条件幂等。实现可能通过多次定位系统调用或远端请求完成整个
    // 窗口，并可能使用中转存储；接口不承诺零复制、零分配、单次系统调用或
    // 固定延迟。可报告的输入、EOF 与后端失败不得 panic。
    /// 从当前逻辑游标精确填满已初始化缓冲区的指定窗口。
    ///
    /// 只有完整成功才把游标一次推进窗口长度；意外文件尾、其它错误或取消均
    /// 保持调用前游标。失败时目标窗口前缀可能已改变，窗口外字节不得改变。
    /// 空窗口直接成功且不推进游标。
    fn read_exact<'a, B>(
        &'a mut self,
        buffer: &'a mut B,
        target: ReadTargetRegion,
    ) -> impl Future<Output = pi_result::Result<()>> + Send + 'a
    where
        B: AsMut<[u8]> + Send + ?Sized + 'a;

    // 从当前逻辑游标朝文件尾读取，并追加到增长型缓冲区逻辑尾部。
    //
    // 本方法结合 [`Self::read_to_end_at`] 的受限增长语义与顺序资源的独占
    // 逻辑游标。它从调用开始时的游标 `C` 读取；`buffer` 是调用方独占借用
    // 的增长型承载体；`limit` 是本次最多可以新增的有效字节数。参数顺序
    // 固定为“目标承载体、增长上限”。
    //
    // `&mut self` 使同一资源上的顺序读取、游标变更和关闭在类型层自然串行。
    // 本版不提供顺序写入；追加由独立打开的追加资源执行。需要并发且不
    // 改变游标的增长读取应使用 [`Self::read_to_end_at`]，
    // 或通过 namespace 独立打开具有不同逻辑游标的资源。
    //
    // # 追加与成功终止
    //
    // 假设调用开始时缓冲区的完整已初始化视图为 `[0, L)`。本方法必须保留
    // 该前缀，只把新读取且确认初始化的字节追加到逻辑尾部；它不得覆盖旧
    // 内容。实现应优先使用现有备用容量，空间不足时按缓冲区合同自动扩容，
    // 并且只能提交后端确认完成的连续前缀。
    //
    // 成功返回 [`ReadGrowthOutcome`]：在耗尽上限前明确观察到 EOF 时返回
    // [`ReadGrowthOutcome::EndOfFile`]；恰好提交上限允许的新增量时返回
    // [`ReadGrowthOutcome::LimitReached`]，不得额外探测 EOF。`limit == 0`
    // 必须零 I/O、零分配、零修改地返回
    // `LimitReached { appended_bytes: 0 }`，并保持游标 `C`。
    //
    // # 成对渐进提交不变量
    //
    // 与固定 [`Self::read`] 和 [`Self::read_exact`] 的“错误时不推进游标”
    // 不同，增长式顺序读取采用成对渐进提交。每当实现确认新的连续 `n` 字节
    // 已经初始化时，必须在同一不可对调用方观察的提交步骤中：
    //
    // 1. 把这 `n` 字节追加到缓冲区公开逻辑尾部；
    // 2. 把公开逻辑游标向前推进相同的 `n` 字节。
    //
    // Future 结束或被丢弃后始终满足：本次游标增量、缓冲区长度增量和本次
    // 已安全提交的连续字节数三者相等。这样错误后的后缀仍与下一源位置严格
    // 对齐，重试不会因“字节保留但游标回滚”而重复读取。
    //
    // # 前置验证、错误与取消
    //
    // 实现必须在 I/O 前将 `limit` 绑定到调用时逻辑长度，并验证最终长度及
    // 最大文件偏移均可表达。前置验证失败时，缓冲区、游标和后端状态保持
    // 不变。
    //
    // 读取开始后的错误只返回 [`pi_result::Error`]，不返回缓冲区、
    // [`ReadGrowthOutcome`] 或类型化进度。已经成对提交的后缀与游标增量保留，
    // 不回滚；旧前缀必须不变，未初始化字节绝不能进入公开逻辑长度。调用方
    // 若需要恢复失败进度，可以在调用前记录 `buffer.as_ref().len()`，借用
    // 结束后与当前长度比较。
    //
    // 丢弃 Future 后不得再访问 `buffer`，也不得再提交缓冲区或游标进度；
    // 取消前已经完成的成对提交保留。completion adapter 必须先把一个有界
    // 分块读入自有 owned 中转载体，等底层停止访问后，再同步提交该完整分块
    // 及对应游标增量，不能让后台操作持有 `chunk_mut()` 的借用地址。
    //
    // # 并发、MMAP 与类型范围
    //
    // 不同独立打开资源具有独立逻辑游标，但内容操作仍由进程内稳定文件身份
    // 协调器检查。本方法与同一文件待建立或活动的 MMAP 互斥；跨进程修改、
    // 截断和映射不在本接口协调范围内。
    //
    // 返回 Future 为 `Send + 'a`。`B` 必须满足 [`GrowableReadBuffer`] 的
    // 已初始化完整视图与尾部提交合同，并允许独占借用跨线程迁移；不要求
    // `Clone`、`Sync`、`'static` 或写侧的 [`crate::DetachableWriteBuffer`]。
    // 首批内置类型是 `Vec<u8>` 和 [`bytes::BytesMut`]。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法增长调用方缓冲区、渐进推进逻辑游标并执行外部 I/O，不是纯函数，
    // 也不是无条件幂等。分块中转、扩容和复制的成本至少与新增字节数线性
    // 相关；接口不承诺整次事务式回滚、零复制、零分配、单次系统调用、固定
    // 延迟或文件内容快照。
    /// 从当前逻辑游标读取，并追加到增长型缓冲区的逻辑尾部。
    ///
    /// 每一段对调用方可见的新后缀都必须伴随相同大小的游标推进；因此成功、
    /// 错误或取消后，缓冲区本次增长量与游标增量保持一致。成功通过
    /// [`ReadGrowthOutcome`] 区分文件尾和限额耗尽；零限额不执行 I/O 或推进。
    fn read_to_end<'a, B>(
        &'a mut self,
        buffer: &'a mut B,
        limit: ReadGrowthLimit,
    ) -> impl Future<Output = pi_result::Result<ReadGrowthOutcome>> + Send + 'a
    where
        B: GrowableReadBuffer + Send + 'a;

    // 把一个连续写入源完整追加到调用时的文件或远端对象逻辑尾部。
    //
    // 本方法是本版唯一的严格尾部追加入口。它不是共享游标顺序写入、随机
    // 写入、全文件覆盖或“先定位到尾部再写入”。`buffer` 按值传入，其
    // [`AsRef::<[u8]>::as_ref`] 视图是本次调用全部、连续且已经初始化的权威
    // 字节序列；视图没有隐藏游标，也不允许 adapter 只提交其中一个子范围。
    // 参数顺序固定为“独占文件资源、拥有型写入源”，本方法没有文件偏移、
    // 内存范围或隐式追加选项。
    //
    // # 成功、空输入与完成点
    //
    // 只有权威视图的全部字节都完成一次逻辑追加时才返回 `Ok(())`。成功不
    // 返回 `B`：owned 输入被本次操作消费，借用型 `B` 则只消费引用值。空
    // 视图已经完整追加，必须零文件 I/O、零远端请求、零 buffer 脱离和零
    // 文件内容副作用地返回 `Ok(())`。
    //
    // 每个追加资源必须来自一次独立打开，并由后端提供真正的尾部追加语义；
    // 不能用“先读取文件尾、再从该位置写入”或克隆同一打开状态模拟。后端
    // 无法保证整次调用的严格尾部追加合同，就必须在副作用前返回不支持。
    //
    // 本方法成功不表示 `sync_data`、`sync_all`、目录同步、MMAP 脏页刷新或
    // 远端强持久化已经完成，也不保证掉电、操作系统崩溃、控制器失信、介质
    // 或硬件损坏后的数据存续。需要持久性时必须使用后续独立冻结的显式
    // 接口，不能从 `append` 成功自行推导。
    //
    // # 同文件 MMAP 写入源禁令
    //
    // 已建立的映射可以与目标文件的尾部追加同时存活，但目标文件任一活动
    // 映射及其派生视图绝不能反向作为本次追加源。该情况必须在 buffer 脱离
    // 和任何文件副作用之前失败。
    //
    // 禁令覆盖直接传入的 [`crate::ReadMmapHandle`]、其共享引用，以及从映射
    // 零复制视图派生的普通切片和子切片。
    // 不同文件的映射可以作为追加源；调用方已经显式复制到独立 `Vec<u8>`、
    // `bytes::Bytes` 等普通存储的字节也不再是映射地址别名，可以用于原文件
    // 追加。空视图不访问任何字节，不形成地址区间冲突。
    //
    // 同文件映射源失败的 [`BufferFailure::error`] 使用
    // [`pi_result::ErrorKind::Conflict`] 作为公共粗粒度分类，并保留能够
    // 明确说明“同文件映射不能作为追加源”的精细错误上下文；不得降级为
    // 含糊的通用 I/O 文案。它必须返还调用时的同一个原始 `B`，进度严格为
    // `TransferProgress::Exact { bytes: 0 }`，且文件内容不变。
    //
    // # 普通错误、原始 buffer 与部分进度
    //
    // 普通错误通过 [`BufferFailure<B>`] 同时返回 `pi_result` 错误、调用时的
    // 同一个原始 `B` 和 [`crate::TransferProgress`]。返还同一个值不仅要求
    // 字节相等：allocation、容量、引用身份、`Cow` 变体、映射句柄或池租约
    // 等受 [`DetachableWriteBuffer`] 合同保护的状态也必须恢复。adapter 只有
    // 在后端已经停止访问脱离载体后才能执行恢复。
    //
    // 所有副作用前失败都必须报告 `Exact { bytes: 0 }`。已经开始追加但无法
    // 可靠证明实际完成量时必须报告 [`crate::TransferProgress::Unknown`]；
    // 只有具备更强证据时才能报告精确前缀或可信下限。错误返还完整原值不
    // 表示可以从头重试。
    //
    // # 非幂等性与重试
    //
    // 非空追加具有文件内容副作用且不是幂等操作。只有错误进度明确为
    // `Exact { bytes: 0 }`，并且错误原因本身允许重试时，重新提交完整 `B`
    // 才不会因为本次调用重复追加字节。`AtLeast` 或 `Unknown` 要求调用方先
    // 通过外部协议、记录边界或后端状态消除不确定性；不得盲目从头重试。
    // 空输入没有文件内容副作用，重复调用仍返回成功。
    //
    // # 并发、独立句柄与映射共存
    //
    // `&mut self` 在类型层禁止并发驱动同一个公开文件资源。多个 appender
    // 若要操作同一文件，必须分别通过 namespace 新开资源；不得使用公开
    // `Clone`、`File::try_clone`、`dup`、`DuplicateHandle` 或等价方式复制
    // 同一个底层打开状态。
    //
    // 不同独立资源仍必须按稳定文件身份汇合到进程内协调器。同一受管文件
    // 任一时刻最多一个完整公开追加进入实际执行，执行租约覆盖全部
    // `write_all`、短写续写、后端完成动作及取消后的真实后台寿命。已有映射
    // 不阻止追加，追加也不会扩大既有映射的范围快照；正在执行的追加则阻止
    // 新映射捕获长度并建立视图。
    //
    // 这些保证只覆盖同一进程、同一份库协调状态内的受管入口。其它进程、
    // 绕过本库的文件句柄、另一份未共享注册表的库实例或库外映射仍可能修改
    // 文件、插入其它追加或破坏相干性；本方法不提供跨进程锁或任意长度的
    // 全有或全无记录事务。
    //
    // # 取消与资源寿命
    //
    // 调用方丢弃 Future 表示停止等待，不表示已经撤销追加，也没有返回
    // [`BufferFailure`] 的通道。副作用前取消不得开始文件写入；一旦内部拥有
    // 型操作接管脱离 buffer，adapter 必须让该操作继续持有文件资源、脱离
    // 载体和稳定身份租约，直到后端确定成功或停止访问后失败。租约不能随
    // 调用方 Future 一起提前释放，否则另一个独立 appender 可能与尚未排空
    // 的写入交错。
    //
    // 取消不会回滚已经追加的字节，也不能向已经离开的调用方交付最终进度。
    // 内部完成所有者最终负责释放 buffer、文件和租约；它不得要求调用方继续
    // 轮询原 Future 才能保证内存安全或恢复同文件的受管串行化。
    //
    // # 泛型、线程与生命周期
    //
    // `B: DetachableWriteBuffer` 同时提供完整只读视图与按需产生独立载体的
    // 能力；它已经继承 `AsRef<[u8]>`，因此不重复列出该约束。`B: Send + 'a`
    // 允许 owned 值或带调用期借用的引用随公开 Future 在线程间迁移，不要求
    // `B: Sync`、`Clone` 或 `'static`。
    //
    // `B::Detached: Send` 允许完成所有者跨线程持有独立载体；其 `'static`
    // 已由 [`DetachableWriteBuffer::Detached`] 保证。`B::Recovery: Send + 'a`
    // 允许正常错误路径跨线程保留一次性恢复令牌，同时继续支持其中保存
    // `&'a [u8]`、`&'a Vec<u8>` 或其它调用期引用。运行时要求顶层任务为
    // `Send + 'static` 时，调用方可以让 `async move` 任务拥有文件资源和
    // owned buffer，再在任务内部调用本方法。
    //
    // # 副作用、panic 与成本
    //
    // 非空调用会修改文件或远端对象，并可能修改进程内队列、稳定身份状态、
    // 引用计数、日志和指标，因此不是纯函数。它可能异步等待同文件追加租约、
    // 阻塞线程池和远端服务，不承诺固定延迟、公平调度、无分配或无用户态
    // 复制。owned allocation 通常可直接移动，共享载体通常只增加引用计数；
    // 借用输入为满足取消寿命可能需要 O(n) 复制，实际写入成本至少与字节数
    // 线性相关。
    //
    // 所有可报告的输入、能力、并发、资源和后端错误都必须通过返回值表达，
    // 不得 panic。全局分配器终止进程、第三方违反
    // [`DetachableWriteBuffer`] 安全合同或调用方使用 `unsafe` 制造失效切片，
    // 不属于本方法能够恢复的普通错误保证。
    /// 把整个连续缓冲区严格追加到调用时的文件逻辑尾部。
    ///
    /// 这是尾部追加，不是“读取长度后定位写入”。同一稳定文件的多个受管追加
    /// 以完整调用为单位串行，字节不得相互穿插。已经存在的映射可与追加并存，
    /// 但正在执行追加时不能建立新映射；同一文件的映射及其派生视图不得作为
    /// 本次追加源，不同文件的只读映射可以作为源。
    ///
    /// 成功只返回 `()`。普通失败通过 [`BufferFailure`] 返还原始 `B` 和可证明
    /// 的写入进度，便于调用方决定是否重试；取消没有返还通道，也不回滚已经
    /// 追加的字节。空输入成功且不改变内容。该完成点不等于强持久化，必要时
    /// 还应显式调用 [`Self::flush`]。
    fn append<'a, B>(
        &'a mut self,
        buffer: B,
    ) -> impl Future<
        Output = pi_result::RawResult<(), BufferFailure<B>>,
    > + Send
           + 'a
    where
        B: DetachableWriteBuffer + Send + 'a,
        B::Detached: Send,
        B::Recovery: Send + 'a;

    // 使当前文件或远端对象的全部逻辑内容和最终长度与输入完全一致。
    //
    // 本方法是全文件原地覆盖的唯一普通 I/O 入口。它不是从共享游标开始的
    // `write_all`，不是任意偏移随机写入，也不是调用方可观察的“先截断、再追加”两步
    // 组合。`buffer` 按值进入，其 [`AsRef::<[u8]>::as_ref`] 视图是本次请求全部、
    // 连续且已初始化的权威新内容。方法不接受文件偏移、内存子范围、追加选项、
    // 隐式游标或持久化等级。
    //
    // # 访问角色与文件身份
    //
    // 只有以 [`crate::FileAccessMode::Overwrite`] 创建或打开的资源才允许调用本方法。
    // 其它角色必须在 buffer 脱离、后端排队或任何文件副作用之前返回明确的能力
    // 错误，并交还原始 `B`、`TransferProgress::Exact { bytes: 0 }` 与
    // [`crate::OverwriteTargetEvidence::Unchanged`]。已知不能实现这项语义的 adapter 还必须
    // 在 namespace 打开 `Overwrite` 角色时尽早失败，不得返回一个伪可用资源。
    //
    // “原地”表示本方法不通过临时文件替换目录项，不改变受管资源在本库中的
    // 稳定文件身份，也不承诺故障原子性。需要“写临时文件、强刷新、原子替换”的
    // 调用方必须使用未来单独冻结的 namespace 替换接口，不得从本方法推导该能力。
    //
    // # 成功、空输入与普通完成点
    //
    // 只有目标的全部逻辑字节逐字节等于权威输入视图，且目标逻辑长度精确等于
    // `buffer.as_ref().len()` 时才能返回 `Ok(())`。成功不返回 `B`：owned 值由本次
    // 操作消费，借用型 `B` 则消费外层引用值。目标原有但超出新输入长度的尾部
    // 必须消失，不得遗留旧字节。
    //
    // 空输入不是无副作用快速成功：它要求目标最终为空文件。adapter 必须取得相同的
    // 排他租约，必要时将目标长度变为零，并等待本方法定义的普通完成点。
    // 空输入不传输 payload 字节，但可以执行文件长度系统调用、远端空对象更新和管道
    // 排空。
    //
    // 普通成功还必须等待 adapter 的完整写入管道排空，不能在后台仍可能访问输入、
    // 继续写文件或报告普通错误时提前返回。该完成点不等于 [`Self::flush`] 的强文件
    // 刷新，也不证明目录项、远端服务副本或掉电后数据已持久化。需要更强完成
    // 保证时，调用方必须在成功后显式调用 `flush`。
    //
    // # 后端能力边界
    //
    // 后端只有在能够等待完整逻辑更新并产生本合同要求的失败证据时才能支持
    // 本角色。更强的原子能力可以使用，但不能削弱公开基线；能力不足时必须
    // 在目标副作用前返回不支持。
    //
    // # 同文件 MMAP 输入禁令
    //
    // 目标文件任何活动映射都与全文件覆盖互斥。因此目标的
    // [`crate::ReadMmapHandle`]、该句柄的共享引用，以及从其零拷贝视图派生
    // 的切片或子切片，都不能反向作为本次覆盖源。该情况必须在 buffer 脱离、
    // 长度修改和任何目标副作用之前失败。
    //
    // 该失败必须交还同一原始 `B`、`TransferProgress::Exact { bytes: 0 }` 和
    // [`crate::OverwriteTargetEvidence::Unchanged`]，并使用能明确表达“同文件映射不能作为覆盖源”
    // 的错误上下文。不同文件的只读映射句柄可以作为输入；其脱离路径可以移动句柄
    // 或仅增加一次引用计数，但本接口不承诺整条操作系统文件传输路径为零拷贝。
    // 空输入不访问任何映射字节，但目标存在活动映射时仍不允许把文件清空。
    //
    // # 普通错误、目标证据与重试
    //
    // Future 正常完成为错误时，[`OverwriteFailure<B>`] 同时返回统一诊断报告、调用时
    // 的同一个原始 `B`、输入连续前缀进度和目标状态证据。返还同一个值不只要求
    // 字节相等；adapter 必须按 [`DetachableWriteBuffer`] 合同恢复 allocation、容量、引用
    // 身份、`Cow` 变体、映射 guard、池租约及其它承诺状态，并确保后端已经停止
    // 访问脱离载体。
    //
    // 输入进度只计算 adapter 能够证明已进入本次权威覆盖处理的连续前缀，不得把
    // 仅复制到库内临时缓冲区的字节冒充为文件处理进度。它与目标证据正交：目标已清空
    // 可以同时报告零输入进度，已处理全部输入也可以仍无法证明远端目标状态。
    //
    // 所有文件副作用前的失败，包括角色不匹配、后端不支持、协调冲突、同文件
    // 映射输入以及脱离失败，都必须报告 `Exact { bytes: 0 } + Unchanged`。目标已经
    // 精确清空但尚未写入时，应报告 `Exact { bytes: 0 } + ExactInputPrefix { bytes: 0 }`。
    // 如果新内容和最终长度已精确形成，但后续普通完成步骤失败，adapter 只有在能够
    // 证明时才可报告 `ExactInputPrefix { bytes: input.len() }`。其它已发生修改但不能精确
    // 证明的结果使用 `MutationStarted`；连是否修改都无法证明时使用 `Unknown`。
    //
    // 本方法不承诺失败原子性。重复使用相同字节在无外部修改时可以形成相同最终
    // 内容，但覆盖仍会更改时间、版本、日志、远端请求和其它副作用，因而不是可以
    // 仅凭相同 buffer 盲目重试的强幂等接口。调用方必须同时检查错误可重试性、
    // [`OverwriteFailure::target_evidence`] 和错误完成后的外部协调状态。
    //
    // # 并发、互斥与跨进程范围
    //
    // `&mut self` 在类型层禁止同一公开文件资源并发驱动两个覆盖或其它独占方法。
    // 同一文件的其它独立打开资源仍必须按稳定文件身份汇合到同一协调器。一次
    // 覆盖的排他租约覆盖权限检查、目标变更、全量写入、短写续写、普通管道排空，
    // 以及取消后仍在运行的真实后台寿命。
    //
    // 在同一协调状态内，本方法不得与普通读取、长度查询、追加、缩短型截断、其它覆盖、
    // 普通强刷新、任何已建立或待建立映射，以及 namespace 的安全删除或以后可能加入的
    // 替换同时执行。默认 `rename` 不取得内容租约；平台因占用状态拒绝时直接返回
    // 明确错误。协调器必须在本次 buffer 脱离和文件副作用前返回明确的冲突错误，不得
    // 让长度查询或读取观察到覆盖中间态。对可能持续任意时长的映射 guard，本方法
    // 尤其不得隐式等待其释放后再开始破坏性操作。
    //
    // 普通打开的资源只承诺同一进程、同一份库协调状态内的上述保证。通过
    // [`crate::CrossProcessFileAuthority`] 打开的资源还必须按已冻结的协调协议取得相应跨进程
    // 排他权限。绕过本库的原生句柄、未加入相同协调域的进程或另一份不共享注册表的
    // 库实例仍可以破坏这些保证，不属于普通资源能够自动防御的范围。
    //
    // # 取消与资源寿命
    //
    // 调用方丢弃 Future 只表示停止等待，不表示覆盖已撤销，也没有能够返回
    // [`OverwriteFailure`] 的通道。在获得排他租约和开始文件副作用前取消，不得修改
    // 目标。一旦目标修改已发生或后端仍可能访问脱离载体，内部完成所有者必须继续
    // 持有文件资源、脱离载体、恢复令牌和稳定身份租约，直到底层成功或确定停止
    // 访问后失败。
    //
    // 取消不回滚已有目标修改，也不能向已离开的调用方交付最终进度或目标证据。
    // 内部完成所有者最终负责释放 buffer、文件和租约；它不得要求调用方继续轮询
    // 原 Future 才能保证内存安全或重新开放同文件协调权限。
    //
    // # 泛型、线程与异步运行时
    //
    // `B: DetachableWriteBuffer` 提供完整只读视图与按需产生独立载体的能力；它已经
    // 继承 `AsRef<[u8]>`，因此不重复列出该约束。`B: Send + 'a` 允许 owned 值或带
    // 调用期借用的引用值随公开 Future 在线程间迁移，不要求 `B: Sync`、`Clone` 或
    // `'static`。
    //
    // `B::Detached: Send` 允许完成所有者把独立载体转移给工作线程或完成式后端；
    // 其 `'static` 已由 [`DetachableWriteBuffer::Detached`] 保证。`B::Recovery: Send + 'a` 允许一次性
    // 恢复令牌跨线程保留调用期引用。方法返回标准 `Future + Send + 'a`，不绑定 Tokio、
    // async-std、Monoio 或其它具体运行时。要求顶层任务为 `Send + 'static` 时，调用方
    // 可以让 `async move` 任务拥有文件资源与 owned buffer，再在任务内调用本方法。
    //
    // # 副作用、panic 与成本
    //
    // 本方法修改文件或远端对象，也可以修改进程内队列、稳定身份状态、引用计数、
    // 日志和指标，因此不是纯函数。它可能等待阻塞工作线程、系统调用和远端服务，
    // 不承诺固定延迟、公平调度、无分配或无用户态复制。owned allocation 通常可以直接
    // 移动，共享载体通常只增加引用计数，借用输入为满足取消寿命可能需要 O(n) 复制；
    // 目标修改和字节传输成本至少与输入长度线性相关。
    //
    // 所有可报告的输入、角色、并发、资源与后端错误都必须通过 [`OverwriteFailure`] 返回，
    // 不得 panic。全局分配器终止进程、第三方违反 [`DetachableWriteBuffer`] 合同，或调用方使用
    // `unsafe` 制造失效切片，不属于本方法能够恢复的普通错误保证。
    /// 使文件全部逻辑内容和最终长度与输入完全一致。
    ///
    /// 本方法是一个整体覆盖操作，不是调用方可观察的“先截断、再追加”。它与
    /// 同一文件的普通读取、追加、截断、其它覆盖、刷新、任何映射以及安全删除
    /// 排它；默认 namespace 改名仅服从平台自身限制。同一文件的映射及其派生
    /// 视图不得作为输入，不同文件的只读映射可以作为输入。
    ///
    /// 成功只返回 `()`。普通失败通过 [`OverwriteFailure`] 返还原始缓冲区、
    /// 写入进度和目标状态证据；取消没有返还通道，也不承诺回滚。空输入表示
    /// 覆盖为空文件。成功不等于强持久化，必要时还应调用 [`Self::flush`]。
    fn overwrite_all<'a, B>(
        &'a mut self,
        buffer: B,
    ) -> impl Future<
        Output = pi_result::RawResult<(), OverwriteFailure<B>>,
    > + Send
           + 'a
    where
        B: DetachableWriteBuffer + Send + 'a,
        B::Detached: Send,
        B::Recovery: Send + 'a;

    // 将当前文件或远端对象的逻辑长度缩短到 `new_len`。
    //
    // 本方法只管理已有内容的保留前缀和丢弃后缀，不接受 buffer，不写入新字节，
    // 也不扩展文件。它与 [`Self::overwrite_all`] 不同：覆盖使目标完全匹配新输入，
    // 截断则只保留原文件的一个连续前缀。
    //
    // # 访问角色与参数
    //
    // 只有以 [`crate::FileAccessMode::Truncate`] 创建或打开的资源才允许调用本方法。
    // 资源打开本身没有截断副作用；只有本方法在成功取得排他租约后才能改变
    // 长度。其它访问角色必须在后端请求或任何文件副作用前返回明确的能力错误。
    //
    // `new_len` 是以字节为单位的零起始逻辑长度，与 [`Self::byte_len`] 的成功类型一致。
    // adapter 必须在同一排他租约中取得当前长度 `current_len`，再执行以下精确分支：
    //
    // - `new_len < current_len`：保留原内容的半开前缀 `[0, new_len)`，丢弃
    //   `[new_len, current_len)`，成功后长度精确等于 `new_len`；
    // - `new_len == current_len`：直接成功，不提交实际的长度修改系统调用或远端更新；
    // - `new_len > current_len`：在任何文件副作用前返回明确的非法输入错误。
    //
    // `new_len == 0` 合法，表示丢弃全部原内容并将目标变为空文件。本方法任何
    // 情况都不得像 [`std::fs::File::set_len`] 那样把超过当前长度的请求解释为扩展文件并
    // 填充稀疏或零字节范围。
    //
    // # 成功、强刷新与普通错误原子性
    //
    // `Ok(())` 表示后端已确认目标逻辑长度精确等于 `new_len`，且保留的字节仍是
    // 调用时原内容的 `[0, new_len)`。成功不表示已完成强刷新、目录同步、远端副本
    // 一致或掉电持久化。需要可观察持久化屏障时，调用方必须在成功后显式调用
    // [`Self::flush`] 并选择需要的 [`FileFlushMode`]。
    //
    // Future 正常完成为 `Err` 时，adapter 必须保证本次调用没有改变目标内容或长度。
    // 因此本方法不需要额外的目标状态证据载体。能力检查、大于当前长度的请求、
    // 协调冲突、活动映射或后端错误均必须满足这一普通错误原子性。一旦 adapter
    // 已经能够证明长度修改成功，就应返回 `Ok(())`；不得因为后续不影响长度事实的
    // 可选诊断、日志或锁清理问题，再返回伪装成“目标未变”的普通错误。
    //
    // 本地 adapter 只能在核验底层文件长度原语具有上述失败边界后接受 `Truncate`
    // 角色。远端 adapter 如果需要通过对象重写、多段提交或结果不确定的请求模拟缩短，
    // 就不能满足本基线，必须在 namespace 打开阶段明确返回不支持，不得降级为结果
    // 不明的破坏性实现。
    //
    // # 并发、MMAP 与跨进程范围
    //
    // `&mut self` 禁止同一公开资源上的截断、覆盖或强刷新并发驱动。对于指向同一
    // 文件的其它独立打开资源，稳定文件身份协调器必须在取得当前长度之前授予一个
    // 排他租约，并持有到底层长度操作已确定完成。
    //
    // 本方法与同文件的普通读取、长度查询、追加、覆盖、其它截断、强刷新、任何已建立
    // 或待建立映射，以及 namespace 的安全删除或以后可能加入的替换互斥。默认
    // `rename` 不取得内容租约；平台因占用状态拒绝时直接返回明确错误。所有冲突必须
    // 在文件副作用前返回明确错误，不得让读取或长度查询观察中间状态。活动映射 guard 可能存活任意
    // 时间，所以遇到映射冲突时必须立即拒绝，不得隐式等待 guard 释放。
    //
    // 普通打开资源只承诺同一进程、同一份库协调状态内的互斥。通过
    // [`crate::CrossProcessFileAuthority`] 打开的资源还必须使用已冻结协调协议取得跨进程排他
    // 权限。绕过本库的原生句柄、没有加入相同协调域的进程，以及另一份不共享注册表的
    // 库实例仍可以修改文件，不属于普通资源的自动安全范围。
    //
    // # 取消、幂等性与副作用
    //
    // Future 在获得排他租约和提交底层长度操作前被丢弃时，不得修改目标。底层
    // 系统调用或远端原语一旦已经提交，取消只表示调用方放弃等待；内部完成所有者
    // 必须继续持有文件资源和排他租约，直到底层返回确定结果。调用方无法从已丢弃的
    // Future 取得最终成功或失败证据，但取消不得导致租约在真实截断完成前释放。
    //
    // 在没有外部重新扩展、替换或修改文件的前提下，重复截断到相同长度在内容层幂等。
    // 调用仍可以产生长度查询、系统调用、远端请求、日志、指标和时间元信息观察，所以
    // 不是纯函数或零副作用操作。错误完成后如果可能存在外部增长，调用方不得不加检查地
    // 盲目重试，否则可能丢弃外部新增内容。
    //
    // # 异步运行时、panic 与成本
    //
    // 返回 Future 为 `Send`，可以在本次 `&mut self` 借用期内跨工作线程迁移，不绑定具体
    // 异步运行时，也不要求借用为 `'static`。本地可能阻塞的长度系统调用必须由内部阻塞
    // 执行设施承载，不得直接占用调用方异步执行器的 poll 线程。本地通常是 O(1)
    // 元信息查询加一次长度修改原语；远端成本由能否提供符合合同的原生能力决定。
    //
    // 所有可报告的参数、角色、冲突、资源和后端错误都必须通过 [`pi_result::Error`] 返回，
    // 合法调用不得 panic。底层平台违反已核验原语合同、进程被终止、掉电、系统崩溃或
    // 硬件损坏不属于本方法的普通错误原子性保证。
    /// 将逻辑长度缩短到 `new_len`。
    ///
    /// 小于当前长度时保留半开前缀 `[0, new_len)`；等于当前长度时无内容
    /// 变化；大于当前长度时返回错误，绝不扩展或填零。该操作与同一文件的
    /// 普通读取、写入、刷新、映射和安全删除排它。成功不等于强持久化。
    fn truncate(
        &mut self,
        new_len: u64,
    ) -> impl Future<Output = pi_result::Result<()>> + Send + '_;

    // 在没有跨进程协调证明的前提下，为指定逻辑范围建立只读文件映射。
    //
    // 本方法把复杂的本地映射、文件身份识别、范围冲突检查和生命周期租约
    // 收拢在 [`FileIo`] 接口之后。调用方得到的只有不透明
    // [`ReadMmapHandle`]；映射内容必须通过该句柄访问，不能取得可与句柄、
    // guard 或范围租约分离的 `memmap2` 对象或原生映射地址。
    //
    // # Safety
    //
    // `unsafe` 只表示本库无法观察和约束其它进程、绕过本库的原生文件句柄，
    // 以及不共享同一协调注册表的库实例。实现仍必须完整执行本库规定的
    // 进程内稳定文件身份、操作互斥和范围租约检查，不能因为调用方进入
    // `unsafe` 而跳过这些防线。
    //
    // 从返回 Future 第一次被轮询开始，直到该 Future 被丢弃，或者成功返回后
    // 最后一个由该映射产生的 [`ReadMmapHandle`] 克隆被释放为止，调用方必须
    // 保证所有不受本库协调的参与者都遵守以下协议：
    //
    // - 不得缩短、覆盖、替换、重建或删除底层稳定文件身份；纯名称改名只有在
    //   平台保持既有句柄与映射仍绑定同一稳定对象时才允许；
    // - 不得通过普通写入或映射写入修改本次逻辑范围内的任何字节，也不得
    //   建立与该范围相交的其它映射；
    // - 如需追加，只能从映射建立时冻结的文件尾之后增加内容，不能改变
    //   已有前缀、缩短文件或使本次映射范围失效；
    // - 必须保证底层文件和设备具有普通文件映射所需的稳定性，不能在句柄
    //   存活期间撤销映射所依赖的存储或访问权限。
    //
    // 违反这些条件不只是普通并发错误：后续安全方法返回的字节切片可能访问
    // 已失效或被并发破坏的映射，从而触发平台异常、进程终止或未定义行为。
    // 仅仅“当前没有发现其它进程”不是长期证明；不能持续控制上述条件时，
    // 调用方必须改用绑定了 [`crate::CrossProcessFileAuthority`] 的
    // [`Self::map_read_only`]。
    //
    // 已经通过 [`crate::FileNamespace::open_with_cross_process_authority`] 绑定
    // authority 的资源不得调用本方法。实现必须在范围预留、sidecar 修改或
    // 原生建图前拒绝这种调用，防止一个已经加入合作式协调域的参与者再从
    // 未协调入口绕过其它进程依赖的协议。此类资源只能调用
    // [`Self::map_read_only`]。
    //
    // Future 在未返回句柄前被丢弃后，调用方的外部协调义务随该 Future 的
    // 生命周期结束。实现不得在取消后读取或公开可能已经建立的映射内容，
    // 并必须由内部完成所有者撤销范围预留、解映射并释放临时资源。
    //
    // # 访问角色与后端能力
    //
    // 只有以 [`crate::FileAccessMode::ReadMmap`] 或
    // [`crate::FileAccessMode::ReadWriteMmap`] 创建或打开的资源才允许调用本
    // 方法。其它角色必须在预留范围、调用原生映射设施或产生其它可观察文件
    // 副作用前返回明确的能力错误。
    //
    // 第一阶段只有能够证明原生文件身份、读权限和映射生命周期的本地普通
    // 文件 adapter 可以成功，包括受支持的 Windows、Linux 文件系统和 Linux
    // `tmpfs`。远端对象、目录、管道、设备、无法取得稳定原生文件句柄的
    // adapter，以及语义未经核验的网络或用户态文件系统必须返回明确的“不支持”
    // 错误，不能把读取并复制到内存伪装成 MMAP。
    //
    // # 范围、文件长度快照与页对齐
    //
    // `range` 按所有权传入，成功后成为映射 guard 和范围租约的一部分；
    // 普通失败不会返还该值。它只是两个 `u64` 边界，不具有大块 buffer 的
    // 重复分配成本，需要重试时调用方可以重新构造相同范围。
    //
    // [`MmapRange`] 已经保证逻辑范围是非空半开区间 `[start, end_exclusive)`。
    // 本方法还必须在同一个映射准入过程内取得文件长度快照，并验证
    // `end_exclusive <= snapshot_len`。等于当时文件尾合法，超过文件尾必须
    // 在原生建图前失败；本接口不会自动扩展文件，也不会建立依赖未来追加
    // 内容的映射。映射成功后的追加不会扩大句柄冻结的范围或长度。
    //
    // adapter 还必须检查所有平台偏移、长度和 `usize` 转换，并处理 Windows
    // 分配粒度或 Linux 页大小等原生对齐要求。原生映射可以在内部向下、向上
    // 扩展到所需边界，但句柄只能公开调用方请求的精确逻辑范围，冲突判断也
    // 必须使用这些逻辑字节范围，不能把内部页对齐扩大误报为公开范围相交。
    //
    // # 并发准入与稳定文件身份
    //
    // `&self` 是有意的：建立映射不读取或推进共享顺序游标，同一资源可以
    // 并发申请不同逻辑范围。实现必须通过内部同步和稳定文件身份注册表把
    // “检查当前操作、冻结长度、检查相交、预留范围、建立映射”组成一个不会
    // 被同文件其它资源绕过的准入过程，而不是依赖 Rust 对单个资源值的借用。
    //
    // 相同稳定文件身份允许同时存在任意数量的映射，但每两个公开逻辑范围
    // 都必须完全不相交，映射权限不改变该规则。并发申请必须先原子预留范围；
    // 一个申请获准后，另一个相交申请立即返回明确的冲突错误，不得同时通过
    // 检查后再分别建图。克隆 [`ReadMmapHandle`] 只共享同一底层映射和同一份
    // 租约，不算新映射，也不重复占用范围。
    //
    // 建立新映射与正在执行或已经获准的追加短暂互斥：遇到追加必须立即返回
    // 冲突，不得等待或在追加过程中猜测文件尾。映射成功后，新的严格追加
    // 可以按追加合同与它并存，但不能扩张或成为该映射的一部分。
    //
    // 新映射还与同文件的随机读取、顺序读取、增长读取、全文件覆盖、截断、
    // 以及 namespace 的安全删除和以后可能加入的替换互斥；普通文件刷新允许共存。
    // 默认 `rename` 不取得内容租约，平台不允许时直接失败。反向准入采用相同
    // 规则。任何活动映射句柄都可能长期存活，所以冲突操作必须返回
    // 明确错误而不是无限等待。普通文件内容路径中，严格追加和普通文件刷新
    // 可以在映射已建立后并存。
    //
    // # 成功、失败与资源生命周期
    //
    // `Ok(ReadMmapHandle)` 表示底层只读映射、精确逻辑范围和稳定身份租约已经
    // 同时建立。句柄的只读字节视图直接借用映射区域，不复制完整文件内容；
    // 实际页面仍可能在第一次访问时由操作系统按需载入。只读句柄可以低成本
    // 克隆并在线程间共享，但所有克隆共同延长同一映射和租约的生命周期。
    //
    // 最后一个克隆被释放时，句柄必须自动撤销进程虚拟地址映射，再释放原生
    // 映射资源、稳定文件身份引用和范围租约。进程此后不再拥有相应虚拟地址
    // 区域；操作系统是否保留共享文件页缓存由平台管理，不属于句柄可以强制
    // 驱逐或承诺的资源。
    //
    // 普通 `Err` 不得返回半初始化句柄，也不得泄漏原生映射或范围预留。建立
    // 只读映射不修改文件内容或逻辑长度；实现仍可能查询元信息、更新进程内
    // 协调表、调用原生映射设施并记录日志或指标，因此不是纯函数。
    // 同一范围在已有句柄存活时重复调用会因相交而失败；句柄全部释放后可以
    // 再次申请，但会建立新的资源，所以本方法不是严格幂等操作。
    //
    // # 取消、异步运行时、panic 与成本
    //
    // Future 在取得范围预留前被丢弃时，不得遗留协调状态。预留或原生建图
    // 已开始后，取消只表示调用方放弃等待；内部完成所有者必须继续持有必要
    // 资源，直到底层操作结束并完成解映射或回滚，不能留下调用方无法释放的
    // 活动映射。取消路径不得访问映射字节。
    //
    // 返回 Future 为 `Send`，可以在 `&self` 借用期内跨工作线程迁移，不绑定
    // Tokio、async-std、Monoio 或其它具体运行时，也不要求借用为 `'static`。
    // 可能阻塞的句柄转换、原生建图或清理必须由 adapter 的阻塞执行设施承载，
    // 不能长期占用调用方执行器的 poll 线程。
    //
    // 本方法不复制映射范围的全部内容，但可能分配协调状态、虚拟地址空间和
    // 页表元数据；后续访问还可能触发缺页和存储 I/O。接口不承诺固定延迟、
    // 零分配、页面常驻或无系统调用。所有可报告的角色、范围、长度、平台、
    // 资源和冲突错误必须进入 [`pi_result::Error`]；满足安全前置条件的合法调用
    // 不得 panic。
    /// 为精确逻辑范围建立只读映射，不提供跨进程协调保证。
    ///
    /// 范围必须非空且完全位于建立时的文件长度快照内。相同文件可以存在多个
    /// 不相交映射；任何相交范围和冲突内容操作都会立即失败而不等待。成功的
    /// [`ReadMmapHandle`] 可零成本克隆并在线程间共享；所有克隆共同代表一个
    /// 逻辑映射。最后一个克隆释放后映射资源自动释放。既有映射可与后续严格
    /// 追加并存，但视图不会随文件增长。
    ///
    /// # Safety
    ///
    /// 调用方必须保证其它进程、库外句柄和不共享本库协调状态的代码，在映射
    /// 存活期间不会截断、覆盖、删除后复用或以其它方式破坏该映射所依赖的文件
    /// 身份和范围。该方法仍会执行全部进程内冲突检查。
    unsafe fn map_read_only_uncoordinated(
        &self,
        range: MmapRange,
    ) -> impl Future<Output = pi_result::Result<ReadMmapHandle>> + Send + '_;

    // 使用资源已经绑定的跨进程协调授权，为指定逻辑范围建立只读文件映射。
    //
    // 这是只读 MMAP 的默认安全入口。它与
    // [`Self::map_read_only_uncoordinated`] 产生相同的 [`ReadMmapHandle`]，但
    // 把无法由普通文件句柄独立证明的跨进程文件稳定性责任集中到更早的
    // [`crate::FileNamespace::establish_cross_process_authority`] `unsafe`
    // 建立点。调用本方法本身不需要再次书写 `unsafe`。
    //
    // # 授权来源与接口位置
    //
    // 当前资源必须由
    // [`crate::FileNamespace::open_with_cross_process_authority`] 独立打开，并
    // 在内部拥有与目标稳定文件身份绑定的授权核心。本方法不重复接收公开
    // authority：这样既不会让调用方把另一文件的令牌误传给已有资源，也不会
    // 在每次热路径建图时重复解析定位符、协调根目录或协议版本。
    //
    // 普通打开的未协调资源调用本方法时，必须在查询目标长度、预留范围、
    // 创建或修改 sidecar、取得原生锁和建立映射之前返回明确的“缺少跨进程
    // 协调授权”错误。实现不得临时自动建立 authority，因为建立 authority
    // 需要调用方承担无法由安全 Rust 推导的外部合作承诺；也不得静默降级到
    // [`Self::map_read_only_uncoordinated`]。
    //
    // 相反，已经绑定 authority 的资源不得调用未协调入口。一个资源在整个
    // 生命周期内只能属于协调或未协调模式之一，不能为单次调用切换锁域。
    //
    // # 安全依据与外部责任
    //
    // 安全性依赖建立 authority 时已经冻结的承诺：所有相关进程和旁路访问
    // 使用同一协调协议、相同物理协调根目录，并且不存在不合作的原始句柄、
    // 映射或 namespace 变更。本方法必须重新核验资源、授权核心、目标稳定
    // 身份、协议状态和协调根目录身份仍然匹配，不能只因资源保存了一个内部
    // 指针就假设外部状态未变。
    //
    // 如果调用方或其它参与者后来违反建立 authority 时的承诺，安全责任追溯
    // 到那个 `unsafe` 建立点；本方法的安全形式不能强制恶意或绕过协议的进程
    // 服从 advisory 文件锁。adapter 自身调用 `memmap2` 或原生建图设施时，
    // 仍必须满足它们的全部安全前置条件，不能把公开方法是安全的当成免检理由。
    //
    // # 访问角色、参数与范围快照
    //
    // 只有 [`crate::FileAccessMode::ReadMmap`] 和
    // [`crate::FileAccessMode::ReadWriteMmap`] 角色可以调用。其它角色、远端
    // 对象、无法证明稳定本地句柄的 adapter，以及未经核验的文件系统必须在
    // 任何建图副作用前返回明确错误。
    //
    // `range` 按所有权传入，成功后由映射 guard 和跨进程范围租约共同持有；
    // 普通失败不返还这个只包含两个 `u64` 边界的值。逻辑范围仍是非空半开
    // 区间 `[start, end_exclusive)`。实现必须在同一个协调式准入流程中冻结
    // 文件长度快照，并验证 `end_exclusive <= snapshot_len`；等于文件尾合法，
    // 超过文件尾失败，方法不会扩容文件或等待未来追加填充范围。
    //
    // 所有偏移、长度、`usize` 转换和平台原生映射限制必须在建图前验证。
    // adapter 可以在私有实现中按 Windows 分配粒度或 Linux 页大小扩大原生
    // 视图，但公开句柄、范围租约和相交判断始终使用调用方指定的精确逻辑
    // 字节范围。后续追加不会扩大既有映射快照。
    //
    // # 进程内与跨进程准入
    //
    // `&self` 允许同一资源并发申请不同范围，但不表示检查可以无同步执行。
    // adapter 必须把本进程稳定身份表与合作进程共享的 sidecar 协议组成一个
    // 逻辑准入过程，至少原子完成：
    //
    // 1. 核验 authority、协议和当前稳定文件身份；
    // 2. 取得短期跨进程准入门闩；
    // 3. 检查冲突操作、冻结文件长度并检查所有已有逻辑范围；
    // 4. 登记本次精确范围并建立可由句柄长期持有的范围租约；
    // 5. 建立原生映射，失败时完整撤销登记；
    // 6. 释放短期准入门闩，只把必要的映射范围租约交给句柄。
    //
    // 短期准入门闩不得在 [`ReadMmapHandle`] 的整个生命周期内保持全局独占，
    // 否则会无意义地阻塞同文件的合法追加和不相交映射。句柄必须持有能够让
    // 其它合作进程发现或尊重本映射范围的长期租约；具体锁文件、范围记录、
    // 原生锁和崩溃清理协议属于 adapter 私有实现，不能泄漏到本接口。
    //
    // 同一稳定文件身份的多个映射只有在公开逻辑范围完全不相交时才能共存，
    // 读写权限不改变相交规则。两个进程或线程并发申请相交范围时只能有一个
    // 成功。克隆成功返回的只读句柄只共享同一映射和租约，不登记新范围。
    //
    // 映射创建与正在执行或已获准的追加短暂互斥；遇到追加必须返回冲突，
    // 不能等待或读取不稳定的文件尾。映射成功并释放准入门闩后，新的严格
    // 追加可以加入同一协议并与映射长期并存，但仍须在映射快照尾部之后增加
    // 内容，不能改变映射范围或原有前缀。
    //
    // 随机读取、顺序读取、增长读取、全文件覆盖、截断、普通文件强刷新、
    // 安全删除和以后可能加入的替换与映射创建或活动映射互斥。协调域中的
    // namespace 改名仍按 authority 协议拒绝；普通未协调 `rename` 则不取得
    // 内容租约，并服从平台占用限制。冲突必须返回明确错误，
    // 不得等待一个可能长期存活的远端进程映射租约。所有合作进程都必须采用
    // 相同矩阵；本方法不能为不同平台悄悄放宽公开语义。
    //
    // # 成功、失败、取消与生命周期
    //
    // `Ok(ReadMmapHandle)` 表示原生只读映射、进程内范围租约和跨进程范围
    // 租约均已建立。句柄拥有全部必要私有核心，所以公开 authority 和原
    // [`FileIo`] 资源可以先行释放。所有句柄克隆共同维持同一租约；最后一个
    // 克隆被释放时必须先停止公开访问并撤销原生映射，再释放进程内和跨进程
    // 范围状态。协调目录不会随句柄析构自动删除。
    //
    // 普通 `Err` 不得泄漏半初始化映射、进程内预留、跨进程范围记录或仍被
    // 其它参与者视为活动的锁。失败不修改目标内容和逻辑长度，但完整且可复用
    // 的协调目录或协议文件可以保留；它们不是活动映射，也不能为了恢复空目录
    // 外观而冒险删除其它进程可能已经加入的协调状态。
    //
    // Future 在任何准入动作前被丢弃时不得产生副作用。取得门闩、登记范围或
    // 提交原生建图后取消，只表示调用方放弃等待；内部拥有型完成者必须继续
    // 到安全停止点，撤销映射和全部活动租约后才释放资源。取消路径不得读取
    // 映射字节，也不得遗留调用方无法取得的幽灵句柄。调用方丢弃 Future 后
    // 不需要继续持有公开 authority 或文件资源来协助清理。
    //
    // # 副作用、幂等性、异步运行时与成本
    //
    // 本方法不修改目标内容或长度，但会查询文件状态、取得文件锁、更新协调
    // 记录和进程内状态、建立虚拟地址映射并可能产生日志或指标，因此不是纯
    // 函数。同一范围在原句柄存活时重复调用因相交而失败；释放后重新调用会
    // 建立新的映射和租约，所以不是严格幂等操作。
    //
    // 返回 Future 为 `Send`，可以在 `&self` 借用期内跨工作线程迁移，不绑定
    // 具体异步运行时，也不要求借用为 `'static`。可能阻塞的 sidecar 打开、
    // 文件锁、身份核验、原生建图和清理必须放入 adapter 的阻塞执行设施，
    // 不得长期占用调用方执行器的 poll 线程。
    //
    // 成功路径不复制整个映射范围，但可能分配进程内协调节点、跨进程记录、
    // 虚拟地址空间和页表元数据；实际页面可以在读取时按需载入。接口不承诺
    // 固定延迟、零分配、零系统调用、无锁或页面常驻。所有可报告错误进入
    // [`pi_result::Error`]，满足先前 authority 安全承诺的合法调用不得 panic。
    /// 为精确逻辑范围建立跨进程协调的只读映射。
    ///
    /// 当前资源必须由有效跨进程授权打开。范围必须非空且完全位于建立时的
    /// 文件长度快照内；同文件仅允许不相交映射，冲突立即失败而不等待。成功
    /// 句柄可低成本克隆和跨线程共享，最后一个克隆释放时自动释放资源。既有
    /// 映射可与后续严格追加并存，但视图不会随文件增长。
    fn map_read_only(
        &self,
        range: MmapRange,
    ) -> impl Future<Output = pi_result::Result<ReadMmapHandle>> + Send + '_;

    // 在没有跨进程协调证明的前提下，为指定逻辑范围建立独占读写文件映射。
    //
    // 本方法只负责从已打开文件资源创建一个不透明
    // [`ReadWriteMmapHandle`]。调用方不能取得底层 `memmap2::MmapMut`、裸地址、
    // 页对齐后的隐藏范围或可与句柄分离的 guard；所有映射读取、修改和刷新
    // 都必须经过返回句柄明确提供的接口。
    //
    // # Safety
    //
    // 本方法是 `unsafe`，因为进程内注册表不能观察其它进程、绕过本库的原生
    // 句柄、另一份不共享状态的库实例或外部映射。实现仍必须完整执行本库的
    // 稳定文件身份识别、操作互斥、范围相交和资源生命周期检查；`unsafe`
    // 不是跳过进程内协调的开关。
    //
    // 从返回 Future 第一次被轮询开始，直到该 Future 被丢弃，或者成功返回的
    // [`ReadWriteMmapHandle`] 被释放且所有取消后内部操作真实结束为止，调用方
    // 必须保证所有不受本库协调的参与者遵守以下协议：
    //
    // - 不得缩短、覆盖、替换、重建或删除底层稳定文件身份；纯名称改名只有在
    //   平台保持既有句柄与映射仍绑定同一稳定对象时才允许；
    // - 不得通过普通读取、普通写入或其它映射访问本次逻辑范围，也不得建立
    //   与该范围相交的只读或读写映射；
    // - 不得撤销映射依赖的文件访问权限、存储、稳定身份或设备能力；
    // - 如需追加，只能从映射建立时冻结的文件尾之后增加内容，不能修改已有
    //   前缀、缩短文件或把本映射及其派生视图作为同文件追加源；
    // - 必须确保其它一切文件操作服从本库公开的映射互斥矩阵。
    //
    // 这些约束同时保护底层映射有效性和安全 Rust 的独占可变借用。违反约束
    // 可能让 [`ReadWriteMmapHandle::as_bytes_mut`] 返回的切片与外部访问重叠，
    // 或访问已经失效的文件映射，从而产生平台异常、进程终止或未定义行为。
    //
    // 已经通过 [`crate::FileNamespace::open_with_cross_process_authority`] 绑定
    // authority 的资源不得调用本方法。实现必须在范围预留、sidecar 修改或
    // 原生建图前返回明确错误，防止一个已加入协调域的参与者绕过协议。该类
    // 资源只能使用后续对应的安全读写映射入口。
    //
    // Future 在未返回句柄前被丢弃后，调用方的外部协调义务随 Future 生命周期
    // 结束。实现不得在取消后读取或修改映射字节，并必须由内部完成所有者撤销
    // 可能已经建立的原生映射和范围预留。
    //
    // # 访问角色与后端能力
    //
    // 只有以 [`crate::FileAccessMode::ReadWriteMmap`] 创建或打开的资源才能调用
    // 本方法。只读映射角色和其它普通 I/O 角色必须在建图副作用前返回明确的
    // 能力错误。
    //
    // 第一阶段只有能够证明稳定原生文件身份、读写权限和映射生命周期的本地
    // 普通文件 adapter 可以成功，包括受支持的 Windows、Linux 文件系统和
    // Linux `tmpfs`。远端对象、目录、管道、设备、无法取得适当原生句柄的
    // adapter，以及语义未经核验的网络或用户态文件系统必须返回“不支持”，
    // 不能用复制 buffer 加回写流程伪装成可写 MMAP。
    //
    // # 范围、长度快照与平台对齐
    //
    // `range` 按所有权传入，成功后由映射 guard 和范围租约持有；普通失败不
    // 返还这个只包含两个 `u64` 边界的值。[`MmapRange`] 保证其为非空半开
    // 区间 `[start, end_exclusive)`，本方法还必须在同一准入过程中冻结文件
    // 长度并验证 `end_exclusive <= snapshot_len`。等于文件尾合法，超出文件尾
    // 失败；创建读写映射绝不自动扩容文件或写入初始化字节。
    //
    // adapter 必须验证平台偏移、长度、`usize` 转换以及 Windows 分配粒度或
    // Linux 页大小等原生限制。内部原生视图可以为了对齐包含逻辑范围之外的
    // 隐藏前缀或后缀，但公开句柄只能产生精确逻辑范围内的切片，不能通过
    // `DerefMut`、`AsMut` 或裸指针泄漏隐藏字节。
    //
    // 相交判断使用公开逻辑范围，而不是内部页对齐范围。两个逻辑范围即使
    // 落在同一个物理页内，只要字节区间完全不相交也可以分别建图；adapter
    // 必须保证安全 Rust 永远只能为各句柄构造互不重叠的公开切片。底层刷新
    // 可能按页顺带影响更大区域，但不能扩大调用方的可读写权限。
    //
    // # 独占句柄与并发准入
    //
    // 方法使用 `&self`，因为文件资源本身只创建映射，不承载映射后的共享
    // 可变访问。真正的单写所有权转移到 [`ReadWriteMmapHandle`]：它可整体
    // `Send` 到另一线程，但不实现 `Clone`、`Copy` 或 `Sync`，只能通过
    // `&mut self` 取得可写视图或执行刷新。
    //
    // `&self` 也允许同一文件资源并发申请不同范围。实现不能只依赖单个资源
    // 的 Rust 借用，必须通过稳定文件身份注册表原子完成操作冲突检查、文件
    // 长度快照、范围相交检查、范围预留和原生建图。两个线程同时申请相交
    // 范围时只能有一个成功，失败方不得留下任何预留。
    //
    // 同一稳定文件身份可以同时存在多个只读或读写映射，但它们的公开逻辑
    // 范围必须两两完全不相交，权限组合不构成例外。可写句柄不能克隆，所以
    // 一项成功的读写映射始终只有一个公开拥有者；把整个句柄移动到另一线程
    // 不建立第二项映射或租约。
    //
    // 新映射与正在执行或已经获准的追加短暂互斥，遇到追加必须立即返回冲突，
    // 不能等待或在变化中的文件尾上建立快照。映射成功后，新的严格追加可以
    // 与句柄读取、修改或刷新并存，但只增加快照末尾之后的内容。双方不组成
    // 事务，不承诺原子提交、跨路径内容可见顺序或联合持久化完成点。
    //
    // 新映射还与同文件的随机读取、顺序读取、增长读取、全文件覆盖、截断、
    // 以及 namespace 的安全删除和以后可能加入的替换互斥；普通文件刷新允许共存。
    // 默认 `rename` 不取得内容租约，平台不允许时直接失败。反向准入使用相同
    // 规则。映射句柄可能长期存在，冲突必须返回错误而不是无限等待。
    //
    // # 修改、刷新与普通 I/O buffer
    //
    // 创建成功本身不修改文件内容或长度。调用方经
    // [`ReadWriteMmapHandle::as_bytes_mut`] 修改字节后，相关映射页可能成为
    // 脏页，但修改不是事务，不提供回滚点，也不因句柄仍存活而自动形成可观察
    // 的持久化证据。
    //
    // 需要同步完成证据时必须显式等待 [`ReadWriteMmapHandle::flush`]。句柄
    // `Drop` 只负责停止访问、解除虚拟地址映射并释放平台资源和范围租约，
    // 不隐式发起新的刷新；操作系统可能自行写回脏页，但调用方不能把这种
    // 行为当作成功合同。
    //
    // 读写映射句柄只实现固定读取目标所需的 `AsMut<[u8]>`，不实现
    // [`DetachableWriteBuffer`] 或通用 `AsRef<[u8]>`，因此不能成为普通追加或
    // 覆盖写入源。同文件存在活动映射时普通读取本来也会被协调矩阵拒绝；
    // 不同文件把本句柄作为固定读取目标时，仍只能修改其公开逻辑范围。
    //
    // # 成功、错误、取消与资源释放
    //
    // `Ok(ReadWriteMmapHandle)` 表示底层读写映射、精确逻辑范围和稳定身份租约
    // 已一起建立。文件资源可以先于句柄释放；句柄必须独立拥有解映射和租约
    // 清理所需的全部私有状态。
    //
    // 普通 `Err` 不得返回半初始化句柄，不得泄漏虚拟地址映射、原生文件映射
    // 资源或范围预留，也不得修改目标内容或长度。实现仍可能查询元信息、
    // 更新进程内协调状态、调用原生建图设施和记录日志或指标，所以本方法
    // 不是纯函数。同一范围在已有映射存活时重试会冲突；释放后再次建立的是
    // 新资源，因此方法不是严格幂等操作。
    //
    // Future 在取得预留前被丢弃时不得遗留状态。预留或原生建图已经开始后，
    // 内部完成所有者必须继续持有必要资源，直到底层结束并完整解映射或回滚，
    // 不能留下调用方无法取得却仍阻塞其它操作的幽灵映射。取消路径不得访问
    // 或修改映射字节。
    //
    // # 异步运行时、panic 与成本
    //
    // 返回 Future 为 `Send`，可以在 `&self` 借用期内跨工作线程迁移，不绑定
    // 具体异步运行时，也不要求借用为 `'static`。可能阻塞的句柄核验、原生
    // 建图和清理必须由 adapter 的阻塞执行设施承载，不能长期占用调用方
    // 执行器的 poll 线程。
    //
    // 建图不复制整个逻辑范围，但可能分配协调节点、虚拟地址空间和页表元
    // 数据；后续读写可能触发缺页、存储读取和脏页写回。接口不承诺固定延迟、
    // 零分配、页面常驻、无系统调用或隐式刷新。所有可报告错误进入
    // [`pi_result::Error`]；满足安全前置条件的合法调用不得 panic。
    /// 为精确逻辑范围建立独占读写映射，不提供跨进程协调保证。
    ///
    /// 范围必须非空且完全位于建立时的文件长度快照内。相同文件只允许多个
    /// 不相交映射；相交范围或冲突内容操作立即失败。成功的
    /// [`ReadWriteMmapHandle`] 可跨线程移动，但不可克隆或跨线程共享；所有读、
    /// 写和刷新必须通过该句柄。句柄释放时自动解除映射，但不会隐式刷新脏页。
    /// 既有映射可与后续严格追加并存，视图不会随文件增长。
    ///
    /// # Safety
    ///
    /// 调用方必须保证其它进程、库外句柄和不共享本库协调状态的代码，在映射
    /// 存活期间不会截断、覆盖、删除后复用或以其它方式破坏该映射所依赖的文件
    /// 身份和范围。该方法仍会执行全部进程内冲突检查。
    unsafe fn map_read_write_uncoordinated(
        &self,
        range: MmapRange,
    ) -> impl Future<Output = pi_result::Result<ReadWriteMmapHandle>> + Send + '_;

    // 使用资源已经绑定的跨进程协调授权，为指定逻辑范围建立独占读写映射。
    //
    // 这是可写 MMAP 的默认安全入口。它返回与
    // [`Self::map_read_write_uncoordinated`] 相同的
    // [`ReadWriteMmapHandle`]，但把其它进程合作、协调根目录一致和旁路句柄
    // 禁止等外部承诺集中到
    // [`crate::FileNamespace::establish_cross_process_authority`] 的 `unsafe`
    // 建立点，因此调用本方法本身不需要 `unsafe`。
    //
    // # 授权来源与防降级
    //
    // 当前资源必须由
    // [`crate::FileNamespace::open_with_cross_process_authority`] 以
    // [`crate::FileAccessMode::ReadWriteMmap`] 角色独立打开。资源内部已经拥有
    // 绑定目标稳定文件身份、namespace/backend 实例、协议版本和协调根目录
    // 身份的私有授权核心，所以本方法不重复接收公开 authority 参数。
    //
    // 未协调资源调用本方法时，必须在查询长度、取得文件锁、更新 sidecar、
    // 预留范围或建立原生映射前返回明确的授权缺失错误。实现不得自动建立
    // authority，因为安全代码无法代替调用方证明全部外部参与者服从协议；
    // 也不得静默调用 [`Self::map_read_write_uncoordinated`]。
    //
    // 反向地，已经绑定 authority 的资源不能使用未协调入口。一个活动资源
    // 在整个生命周期内只能属于一个协调域，不能为某次建图临时绕过或切换
    // 锁协议。
    //
    // # 安全依据和外部保证
    //
    // 本方法必须重新核验授权核心仍对应当前稳定文件身份、协议状态和物理
    // 协调根目录，不能只检查 Rust 类型或内部指针。所有 adapter 内部的
    // `memmap2` 或原生可写映射调用仍须履行其真实安全前置条件。
    //
    // 安全性最终依赖 authority 建立时由调用方承诺：所有相关进程、库实例、
    // 原始句柄、映射和 namespace 变更都加入相同协议，不存在不合作访问者。
    // `fs4` 等 advisory 锁不能强迫绕过协议的进程服从；若该承诺被违反，安全
    // 责任追溯到 `establish_cross_process_authority` 的 `unsafe` 调用点，而
    // 不是把本方法的安全形式解释为操作系统提供了强制隔离。
    //
    // # 参数、范围与文件长度快照
    //
    // `range` 按所有权传入，成功后由原生映射 guard、进程内租约和跨进程
    // 范围租约共同持有；普通失败不返还这个只包含两个 `u64` 边界的值。
    // [`MmapRange`] 已保证非空半开区间 `[start, end_exclusive)`，本方法还必须
    // 在同一个协调式准入流程中冻结文件长度，并验证
    // `end_exclusive <= snapshot_len`。等于文件尾合法，超出文件尾失败；本
    // 方法不得扩容文件、填充字节或等待未来追加形成范围。
    //
    // adapter 必须在原生建图前验证偏移、长度、`usize` 转换和平台映射限制。
    // Windows 分配粒度或 Linux 页大小导致的内部对齐范围不能进入公开接口。
    // 句柄只能构造精确逻辑范围的只读或独占可写切片，范围冲突也只比较公开
    // 逻辑字节区间。
    //
    // 不相交逻辑范围即使位于同一个物理页也可以分别映射。adapter 必须隐藏
    // 原生映射的对齐前后缀，并保证不同句柄产生的安全 Rust 切片不重叠。
    // 页粒度刷新可能顺带推进同页其它脏字节，但不授予访问权，也不为不同
    // 映射建立提交顺序或联合持久化语义。
    //
    // # 进程内与跨进程准入流程
    //
    // 方法使用 `&self`，因为文件资源只负责创建映射；成功后的唯一可写能力
    // 由不可克隆、非 `Sync` 的 [`ReadWriteMmapHandle`] 独占。并发正确性不能
    // 只依赖一个资源值的 Rust 借用，必须同时经过稳定身份表和跨进程协议。
    //
    // adapter 至少需要把以下步骤组成一个逻辑原子准入过程：
    //
    // 1. 核验资源角色、授权核心、协议和当前稳定文件身份；
    // 2. 取得短期跨进程准入门闩，并加入进程内对应身份的准入状态；
    // 3. 检查所有冲突操作，冻结文件长度并验证逻辑范围；
    // 4. 同时检查进程内和合作进程登记的只读、读写映射范围；
    // 5. 登记本次范围，并建立可由返回句柄长期拥有的范围租约；
    // 6. 建立原生读写映射；失败时完整撤销进程内和跨进程登记；
    // 7. 释放短期准入门闩，只把必要的长期范围状态交给句柄。
    //
    // 短期门闩不得在句柄整个生命周期内保持全局独占，否则同文件合法追加
    // 和其它不相交映射会被永久阻塞。长期范围租约必须足以让其它合作进程
    // 原子发现并拒绝相交申请；具体锁文件、租约文件、原生锁句柄和崩溃恢复
    // 机制属于 adapter 私有实现。
    //
    // 多个线程或进程并发申请相交范围时只能有一个成功。只读映射和读写映射
    // 采用同一范围集合，权限不同不构成相交例外。成功句柄不可克隆，因此一项
    // 读写映射只有一个公开所有者；把整个句柄 `Send` 到另一线程不创建新映射
    // 或新租约。
    //
    // # 操作互斥与追加例外
    //
    // 映射创建与正在执行或已获准的追加短暂互斥。遇到追加时必须立即返回
    // 冲突，不得等待或在变化中的文件尾上猜测快照。映射成功并释放准入门闩
    // 后，新的严格追加可以加入协议并与映射长期并存，但只能在冻结快照末尾
    // 之后增加内容，不能改变映射范围或已有文件前缀。
    //
    // 映射修改、映射刷新和追加互不组成事务：接口不承诺两条路径的原子提交、
    // 统一可见性顺序或联合持久化完成点。需要映射页完成证据时调用句柄的
    // [`ReadWriteMmapHandle::flush`]；普通追加的强文件屏障由 [`Self::flush`]
    // 提供，映射存活时可以调用，但不能互相替代两条路径的完成证据。
    //
    // 新映射还与同文件的随机读取、顺序读取、增长读取、全文件覆盖、截断、
    // 以及 namespace 的安全删除和以后可能加入的替换互斥。普通文件刷新
    // 不阻止建立新的合法映射。
    // 协调域中的 namespace 改名仍按 authority 协议拒绝；普通未协调
    // `rename` 不取得内容租约并服从平台占用限制。反向准入采用同样规则。
    // 映射可能长期存活，所以冲突必须返回明确错误，不能等待
    // 一个可能永不释放的其它进程租约。
    //
    // # 返回句柄、修改与释放
    //
    // `Ok(ReadWriteMmapHandle)` 表示原生读写映射、精确逻辑范围、进程内租约
    // 和跨进程租约均已建立。句柄拥有全部必要私有核心，公开 authority 和原
    // [`FileIo`] 资源可以先行释放而不使映射失效。
    //
    // 句柄实现 `Send`，但不实现 `Clone`、`Copy` 或 `Sync`。调用方只能通过
    // [`ReadWriteMmapHandle::as_bytes`]、
    // [`ReadWriteMmapHandle::as_bytes_mut`] 和显式刷新访问映射；不能获得裸
    // 指针、可分离 guard、通用写入源能力或底层映射对象。
    //
    // 映射字节修改不是事务且没有自动回滚。最后释放句柄时必须先停止公开
    // 访问并解除原生虚拟地址映射，再释放平台资源、进程内范围和跨进程租约。
    // `Drop` 不隐式执行一次新刷新；未显式刷新时操作系统是否以及何时写回
    // 脏页不构成调用方可依赖的成功证据。协调目录也不会随句柄析构删除。
    //
    // # 错误、取消与副作用
    //
    // 普通 `Err` 不得返回半初始化句柄，也不得泄漏原生映射、进程内预留、
    // 跨进程活动范围记录或锁租约。失败不得修改目标内容和长度；完整且可以
    // 复用的协调目录或协议文件可以保留，因为删除它们可能破坏其它参与者。
    //
    // 从未轮询的 Future 不得产生副作用。取得门闩、登记范围或提交原生建图
    // 后取消，只表示调用方放弃等待；内部拥有型完成者必须继续到安全停止点，
    // 解映射并撤销所有活动租约，不能留下调用方无法取得的幽灵句柄。取消路径
    // 不得读取或修改映射字节，调用方也不必继续持有公开 authority 或文件
    // 资源协助清理。
    //
    // 本方法不主动修改文件内容或长度，但会核验身份、打开 sidecar、取得锁、
    // 更新协调记录和进程内表、建立虚拟地址映射并可能记录日志或指标，所以
    // 不是纯函数。同一范围在旧句柄存活时重试会冲突；释放后重建产生新资源，
    // 因而不是严格幂等操作。
    //
    // # 异步运行时、panic 与成本
    //
    // 返回 Future 为 `Send`，可以在 `&self` 借用期内跨工作线程迁移，不绑定
    // 具体异步运行时，也不要求借用为 `'static`。可能阻塞的 sidecar 打开、
    // 文件锁、身份核验、原生建图和清理必须由 adapter 的阻塞执行设施承载，
    // 不能长期占用调用方执行器的 poll 线程。
    //
    // 成功路径不复制整个映射范围，但可能分配协调节点、跨进程范围记录、
    // 虚拟地址空间和页表元数据；后续访问可能产生缺页、存储读取和脏页写回。
    // 接口不承诺固定延迟、零分配、零系统调用、无锁或页面常驻。所有可报告
    // 错误进入 [`pi_result::Error`]，满足 authority 建立承诺的合法调用不得
    // panic。
    /// 为精确逻辑范围建立跨进程协调的独占读写映射。
    ///
    /// 当前资源必须由有效跨进程授权以读写映射模式打开。范围必须非空且完全
    /// 位于建立时的文件长度快照内；同文件仅允许不相交映射，冲突立即失败。
    /// 成功句柄可跨线程移动，但不可克隆或共享；所有映射内容读、写和映射页
    /// 刷新必须通过它。文件资源也允许普通文件刷新，但不替代映射页完成保证。
    /// 句柄释放时自动解除映射，但不会隐式刷新脏页。既有映射可与严格追加
    /// 并存，视图不会随文件增长。
    fn map_read_write(
        &self,
        range: MmapRange,
    ) -> impl Future<Output = pi_result::Result<ReadWriteMmapHandle>> + Send + '_;

    // 等待本文件在该屏障之前已完成的普通写入达到强文件刷新完成点。
    //
    // 本方法为普通文件 I/O 路径建立一个可观察的持久化屏障。它与
    // [`crate::ReadWriteMmapHandle::flush`] 分属两条访问路径：本方法刷新
    // 通过受管普通文件句柄完成的写入；映射产生的脏页必须由持有 guard 的
    // 可写映射句柄刷新，不能借本方法绕过映射句柄的生命周期和权限边界。
    //
    // # 完成点与后端能力
    //
    // `mode` 按值指定本次最低完成等级：[`FileFlushMode::Data`] 要求至少
    // 刷新文件内容和恢复这些内容所必需的状态；
    // [`FileFlushMode::DataAndMetadata`] 还要求刷新文件自身元信息。对受支持
    // 的本地文件，两者分别对应 `async_fs::File::sync_data()` 与
    // `async_fs::File::sync_all()` 的完成等级。平台可以用后者满足前者，
    // 不能以较弱原语满足较强请求。
    //
    // 实现不能把 `AsyncWrite::flush()`、`async-fs` 写管线排空或 Fusio 的
    // 普通 `Write::flush()` 冒充任一模式：这些操作最多证明用户态/适配层
    // 写入已被推向下一层，不能统一证明请求的强文件刷新已经完成。
    //
    // 远端 adapter 只有在后端提供可核验、可等待且不弱于所选 `mode` 的
    // 持久化完成点时才可返回成功；普通 Fusio `Write::flush()` 本身不足以
    // 满足该条件。缺少相应能力的后端必须在不产生文件内容或持久化副作用的
    // 前提下返回 [`pi_result::ErrorKind::Unsupported`]，不得悄悄降级。
    //
    // 本地同步系统调用必须由内部阻塞执行设施承载，不能直接运行在调用方
    // 异步执行器的 poll 线程。返回 Future 为 `Send`，可以在本次独占借用期
    // 内跨工作线程迁移；它不要求 `'static`，也不绑定 Tokio、async-std、
    // Monoio 或其它具体运行时。
    //
    // # 文件级排序与并发
    //
    // `&mut self` 串行化同一公开资源的操作；不同独立资源上的追加、读取、
    // 元信息、映射建立/使用与普通刷新可并存。覆盖、截断和安全删除等
    // 破坏性全文件操作必须在双方准入上与进行中的刷新互斥。
    //
    // `Ok(())` 覆盖调用前已成功完成的受管普通写入和长度变更，不证明另一
    // 资源上仍在进行或之后才开始的追加也已完成同步。需要为某次追加取得
    // 证据时，调用方先等待 append 成功，再等待 flush 成功。取消追加的
    // 等待者须确认后台写入完成后再取得一个新的显式刷新结果。
    //
    // # 与 MMAP 共存及职责分离
    //
    // 任意同文件只读/可写映射存活或建立中，本方法仍可进入；文件刷新不会
    // 截断文件、扩大映射、释放地址空间或提供映射数据访问路径。ReadWriteMmap
    // 文件资源也可请求本方法，但只读 Read/ReadMmap 不获得刷新权限。
    //
    // 允许在映射写后调用普通文件刷新，并不等于替代映射专属刷新保证。
    // Windows 映射视图的脏页需要先经 FlushViewOfFile；映射刷新负责这一
    // 跨平台差异，普通文件刷新不能单独宣称所有映射写都已同步完成。
    // 本版不提供把两条路径合并为原子提交的接口。
    //
    // # 成功边界与不保证事项
    //
    // 成功表示本机受支持文件系统/设备或远端后端明示的强刷新原语已经成功
    // 返回，并至少达到所选 [`FileFlushMode`]。`Data` 不承诺权限、时间戳等
    // 全部元信息，但允许后端连带刷新；`DataAndMetadata` 覆盖文件自身元
    // 信息。两者都不自动同步父目录项，不提交创建、删除或改名协议，不组成
    // 跨文件事务，也不建立与外部进程未受管写入之间的顺序。操作系统可能
    // 顺带刷新由其它句柄或进程产生的脏状态；这只是允许的附带效果，不扩张
    // 本库可证明的写入集合。
    //
    // 本合同不承诺掉电、操作系统崩溃、失信硬件缓存或硬件损坏后的绝对
    // 持久性。Linux `tmpfs` 等易失性文件系统上的成功只表示相应内核刷新
    // 原语已经完成，不会把内存介质变成断电后可恢复的非易失存储。远端成功
    // 也只能达到该后端明确声明并由 adapter 核验的完成层级。
    //
    // # 错误、取消与资源生命周期
    //
    // 所有可报告失败进入 [`pi_result::Error`]，本方法不得 panic。底层刷新
    // 可能在已经提交部分或全部脏状态后失败；错误不回滚文件，也不能证明
    // “完全未持久化”或“已经全部持久化”。文件资源保持有效，调用方可以在
    // 排除冲突或后端故障后再次调用本方法取得新的可观察完成证据。
    //
    // Future 在取得文件级屏障租约前被丢弃时，不得启动强刷新。租约已经
    // 取得或底层同步调用已经提交后，取消只表示调用方放弃等待；内部完成
    // 所有者必须继续持有文件资源、稳定身份状态和屏障租约，直到系统调用
    // 真实结束并完成协调状态收尾。取消不能提前放行覆盖/截断等破坏性
    // 操作或释放后台文件资源。被取消的调用不向调用方提供成功证据；若业务仍需要该证据，
    // 必须在资源重新可用后再次显式刷新。
    //
    // 本 trait 不通过 `Drop` 隐式执行强刷新，也不把资源析构视为成功证据。
    // 当前 API 不提供显式 `close()`；需要持久化保证的业务必须在资源离开其
    // 提交路径前显式等待本方法成功。
    //
    // # 副作用、幂等性与成本
    //
    // 本方法不产生新的文件内容，但会执行系统调用或远端请求、占用阻塞
    // worker、更新进程内协调状态，并可能触发设备写回、日志和指标，因此不
    // 是纯函数。没有后续写入时重复调用是内容效果可重复的安全屏障，但每次
    // 都可能执行真实刷新、产生独立错误和附带刷新其它脏状态，不能视为无
    // 副作用的严格幂等操作。
    //
    // 时间由脏数据量、文件系统、设备、远端服务和阻塞池排队共同决定；接口
    // 不承诺 O(1) 延迟、公平性、无等待、无分配或固定完成时间。
    /// 等待本文件在该屏障之前完成的普通写入达到指定刷新等级。
    ///
    /// [`FileFlushMode::Data`] 至少刷新内容及恢复内容所必需的状态；
    /// [`FileFlushMode::DataAndMetadata`] 还要求刷新文件自身元信息。若后端不能
    /// 提供所选等级，必须返回“不支持”，不能把普通写入管线排空冒充强刷新。
    /// 支持追加、覆盖、截断与读写映射模式的文件资源。只读/可写映射、独立
    /// 追加和其它刷新可以并存；仅与覆盖、截断等全文件破坏性操作互斥。
    /// 要确认一次追加的同步完成，先等待追加成功，再等待本方法成功；本次
    /// 刷新不保证其它资源上尚未完成或之后才开始的追加也已同步。
    ///
    /// 映射写后允许调用本方法，但它不替代 [`ReadWriteMmapHandle::flush`]
    /// 的映射脏页完成保证。成功不保证掉电、系统崩溃、硬件缓存
    /// 失信或介质损坏场景。
    ///
    /// 错误不回滚文件，也不能证明完全未刷新；排除原因后可重试。取消只停止
    /// 等待，已开始的请求可能继续完成，不能提前放行破坏性全文件操作。
    /// 本方法有写回副作用；无新修改时可重复调用，但结果和耗时不保证幂等，
    /// 也不承诺固定延迟。文件资源释放不会隐式提供一次成功刷新证据。
    fn flush(
        &mut self,
        mode: FileFlushMode,
    ) -> impl Future<Output = pi_result::Result<()>> + Send + '_;
}