Module scan 

目录扫描：找出 .omy 文件并用已缓存的凭据自动匹配。

只读文件头，不读整个文件

这是本模块最重要的性质。识别一个 .omy 文件并尝试解锁，只需读取开头的 若干百字节：

读 480 B → 比对 magic (8 B) → 解析固定头 (96 B) → 逐凭据试解 slot 区 (384 B)
        → 若需文件名，补读 TLV 区（通常再几十到几百字节）

载荷完全不碰。一个 4 GiB 的加密视频与一个 1 KiB 的加密文本，扫描成本相同。

⚠️ 注意 MIN_PROBE_SIZE（480）与 file::PEEK_SIZE（96）的区别： 后者只够解析固定头，不足以尝试解锁。见 MIN_PROBE_SIZE 的文档。

扫描一个文件要花多久

每个文件每个凭据只做一次 HKDF + 一次 AEAD 解包尝试：

操作	耗时
HKDF-SHA256	13.2 µs
Argon2id（已被会话缓存，扫描时不执行）	180 ms

实测 500 文件 × 5 密码 = 171 ms。若每个文件都跑 Argon2 则需 450 s（慢 2,627×）。

因此扫描器必须接收已解锁的 SessionKeys，而不是密码。

不做全盘扫描

按用户要求与平台限制（iOS 根本不允许、Android 的全盘权限过审困难、 macOS 需要完全磁盘访问授权），本模块只扫描调用方明确给定的目录。

Structs

ScanHit

单个已识别文件的扫描结果。

ScanOptions

扫描配置。

ScanResult

扫描结果集合。

ScanStats

扫描统计，用于向用户展示进度与结果。

Enums

UnlockOutcome

解锁尝试的结果。

Constants

MIN_FILE_SIZE

omy 文件的最小可能大小：完整头部（含空 TLV 与 MAC）。

MIN_PROBE_SIZE

识别一个文件至少需要读取的字节数：固定头 + slot 区 = 480。

Functions

probe_file

对单个文件尝试识别与解锁。

read_header_area

补读量同时受 parse_limits::MAX_HEADER_LEN 与文件实际长度约束： header_len 来自尚未验证的文件内容，头部不可能比文件本身长。

read_prefix

读文件开头至多 n 字节（文件更短时读到末尾为止）。

scan_dir

扫描一个目录。

scan_dirs

扫描多个目录。