XHIM 附件分片、缓存与审核编排

客户端数据面

XHIM::Media 的 plan_attachment_chunks() 按对象大小、已提交偏移和策略生成 确定性分片。默认 4 MiB，最小 256 KiB，最大 16 MiB，最多 10,000 片；若无法 在上限内完成会失败，不会产生越界或无限分片。恢复偏移落在分片中间时只重传 该分片未提交的后缀。

真正的上传会话 ID、已提交 Part/ETag、累计字节、重试、租约和 revision 仍由 MediaTransport 与 media_tasks 持久化。任何旧进程、旧账号 Epoch 或旧 revision 的进度回调都不能推进任务。消息 Outbox 只能引用服务端 Ready 的稳定 MediaRef，不能保存本地路径或临时签名 URL。

稳定接入入口是：

• xhim_v1_client_create_media_upload：持久化受理，返回当时的任务快照；
• xhim_v1_client_create_media_download：复制稳定 MediaRef 与扁平缓存键后 持久化受理；缓存键不是路径，也不能来自服务端文件名；
• xhim_v1_client_get_media_task：按当前账号查询，不接受调用方传账号；
• xhim_v1_client_cancel_media_task：先安装传输取消 tombstone，再用 revision CAS 收敛持久状态；重复取消幂等；
• xhim_v1_client_open_media_cache_reader：用扁平缓存键和完整 MediaRef 同步打开并复验已提交对象，不返回缓存路径；
• xhim_v1_media_cache_reader_get_size/read/destroy：在 I/O 线程按 offset 分块读取；短读合法，读到 0 表示 EOF，停止读取循环即取消；
• XHIM_V1_EVENT_MEDIA_TASK_UPDATED@1：Payload 仅为 UTF-8 task_id，收到后 查询完整快照。未知状态值必须保留并重新查询。

所有快照 Byte View 仅在回调期间借用。快照有意排除 local_path、Bearer Token、签名 URL 和上传会话凭证，平台需要保留时必须在回调返回前深拷贝允许 公开的字段。

稳定 ABI 的 scoped reader 通过 Product MediaTransport 可选端口打开对象。 Engine 只向端口注入内部缓存根，FFI 不推测或返回路径。Reference POSIX 端口以 no-follow 打开普通单链接文件，复核精确大小和 SHA-256 后把已打开文件句柄交给 reader，因此之后目录项被替换也不会重定向读取。一个 reader 的 read/get-size/ destroy 必须由调用方串行；reader 可独立于 Client 生命周期。未配置安全端口和 Windows Reference 返回 XHIM_V1_STATUS_UNSUPPORTED，不会降级为路径读取。

plan_attachment_cache() 仍可供产品策略层做无文件系统副作用的缓存决策。 Reference Adapter 同时提供实际的安全缓存执行器：Core 只接受最长 128 字节的 扁平缓存键，缓存根固定由账号数据库 storage_path 派生；下载写入 <key>.partial，Range 续传每次发布持久进度前先 fsync，完整大小和 SHA-256 通过后用 no-replace 原子发布。已存在且 Hash 不同的目标不会被覆盖。

执行器用 no-follow 根目录/文件句柄拒绝路径穿越、符号链接和硬链接替换，只在 已打开的 SDK 缓存根内按“过期优先、再 LRU”执行有界配额清理；当前任务和活动 .partial 不参与淘汰，陈旧 partial 按独立 TTL 清理。Reference 的 POSIX 安全文件写入与 reader 端口已覆盖 iOS/macOS/Android/HarmonyOS/Linux；Windows 构建 当前会 fail closed，正式 Windows 产品包必须接入等价的 reparse-point-safe 文件端口后再打开下载能力。

服务端控制面

CompleteUpload 的固定状态流为：

pending → 对象长度/Hash/MIME 校验 → review_pending → ready | rejected

审核通过前不签发下载授权。ports.MediaReviewer 是唯一审核端口，可替换为病毒 扫描、DLP、图片/文本内容审核或内部人工队列；审核方返回 approved、 pending 或 rejected。pending 会持久保留并允许客户端稍后重试 Complete， rejected 永久阻止下载。

仓库内 mediareview/policy 只是保守 MIME 预筛，拒绝脚本、HTML 和可执行格式， 不是第三方病毒扫描服务。客户生产环境如果要求内容安全，必须提供真实 MediaReviewer Adapter、超时/熔断、回调验签、审核 SLA 和人工复核策略。

必测场景

• 进程在分片上传、完整性校验和审核中分别被杀死后恢复；
• 重复 Prepare/Complete 幂等，旧 revision 不得覆盖新状态；
• 断网、429/5xx、过期签名 URL 和凭证刷新；
• Range 206/Content-Range 不匹配、取消、partial 续传、Hash 不符；
• 缓存满、磁盘满、路径穿越、symlink/reparse point、目标已存在不匹配、 权限撤销、Picker 临时 URI 失效；
• 恶意 MIME 冒充、Hash 不符、超大对象、审核拒绝和审核长时间 pending；
• 换号后缓存、任务、授权和回调完全隔离。