Module fsatomic 

原子文件写入与临时明文文件的生命周期管理。

为什么需要这个模块

加密写入若在中途崩溃或断电，可能留下一个看似完整实则损坏的 .omy 文件—— 头部已落盘、载荷只写了一半，用户以为加密成功并删除了原文件，数据就永久丢失了。

本模块实现规范 §10 的五步流程：

1. 写入 <target>.<pid>.<nonce>.tmp
2. fsync(文件)
3. fsync(父目录)          ← 容易遗漏，但在部分文件系统上必需
4. rename(tmp → target)   ← 同文件系统内原子
5. fsync(父目录)

关于父目录 fsync

只 fsync 文件本身是不够的：文件数据虽已落盘，但「目录里存在这个文件名」 这条元数据可能仍在缓存中。断电后可能出现文件内容完好但目录项丢失的情况。 在 ext4 的 data=ordered 模式、XFS、Btrfs 上这都是真实风险。

Windows 无法直接 fsync 目录，NTFS 的 rename 本身是有日志的元数据事务， 因此该步在 Windows 上跳过（见 sync_dir）。

临时明文文件（旁路 L2/L3/L5）

TempPlaintext 用于「用外部应用打开」场景。它必须处理三个旁路泄露： 系统缩略图缓存、搜索索引、以及文件本身的残留。见该类型的文档。

Structs

AtomicWriter

流式原子写入器。

TempPlaintext

受控的临时明文文件，用于「以外部应用打开」。

Constants

PROGRESS_SUFFIX

断点续传的进度文件后缀（移动端后台挂起场景，规范 §10）。

TMP_SUFFIX

原子写入使用的临时文件后缀。

Functions

cleanup_stale

清理指定目录下遗留的 .tmp 与 .progress 文件。

mark_dir_no_index

标记目录不被系统搜索索引与缩略图缓存收录（旁路 L3/L5）。

restrict_permissions

把文件权限收紧到仅所有者可读写。

sync_dir

fsync 一个目录，确保其中的目录项变更已落盘。

write_atomic

原子地把 data 写入 target。