pi_append_log

当前版本提供追加日志公共 trait、默认 V1 块 codec、固定八位文件 Layout 和文件存储实现；网络与对象存储后端尚未实现。文件 segment 使用无后缀的八位编号，最大编号是 active，其余编号是 closed；允许结构编号缺号，rotate 保留旧 segment 并创建下一个编号。archive 使用同一 namespace 内的 rename，暂不支持跨磁盘 copy。

文件后端基于 pi_async_fs，公共错误使用 pi_result。文件后端采用单 owner：同一物理 root 的多任务必须共享同一个 Arc<FileAppendLog<L>>，而不是重复 build。调用方负责排除同 root 的其他 owner、其他进程、旁路 I/O 和 locator 别名；库不检测或拒绝重复 build。append 接受任意 DetachableWriteBuffer，append_stream 支持把异步 chunk 流作为一个连续逻辑 block 写入。首次底层 append 后的错误或取消只使当前 owner 进入 InvalidState，保留已写前缀；后续操作需 drop 当前 owner 并按恢复规则重新 build。测试使用 Tokio，库本身不绑定具体异步运行时。

本库只发出 tracing 事件；应用可通过 pi_append_log::observability::init_observability 初始化 pi_logger 日志 subscriber。

接口契约、设计取舍及默认 V1 格式提案见 追加日志技术设计提案。

稳定结构 Key

AppendLog::Closed 实现公开的 ClosedStructure trait，通过 structure_key() 返回借用句柄的 &str，用于关联 checkpoint、索引或 manifest 元数据。文件后端统一按 u64 结构 ID 生成至少八位十进制 key（例如 00000001）；自定义 Layout 的路径命名不影响 key，宽于八位的 ID 保留完整数字，不截断。key 不含 root、owner 或 .archive，在同一逻辑日志范围内唯一，owner 重建和归档后保持不变。不同 root 或删除重建不保证唯一，外部应使用 (log_identity, key)。

AppendLogVisitor::visit 的 BlockVisitContext<'_> 同时提供 structure_key: &str 和物理首尾边界。Forward/Backward 以及 active/closed 使用同一 key 规范；context 中的 key 只保证在本次调用期间有效，需要长期保存时应复制。active 有 key，但不是可归档的 Closed。字符串不能构造 FileClosed 或授权归档；archive 仍要求同一 owner 的句柄，重建后应使用本次 build 的 recovered_closed，即使旧句柄 key 相同也会被拒绝。

log_identity 由调用方持久维护：同一逻辑日志的 owner 重建应沿用它，不同日志或删除后重新创建的日志应使用不同值。它不是 owner token，也不是库自动生成的 root 身份。ClosedStructure 的借用绑定句柄生命周期，与 visitor 的单次调用借用不同；需要脱离句柄保存时同样应复制 key。Debug 仅用于诊断，不是持久身份或序列化协议。

0.1 -> 0.2 迁移说明

0.2 是破坏性升级：

• Layout 的 active/closed 命名替换为 segment_name/archive_name；segment 无后缀，最大 ID 为 active，允许缺号，rotate 不重命名旧 segment。
• AppendLog 的 Block 关联类型已移除；append 改用 DetachableWriteBuffer，并新增 append_stream。公共错误改用 pi_result::Result。
• 文件归档仍是在同一 namespace 内执行 rename，不支持跨磁盘 copy。