Himalaya pimdir 队列可见性：让已暂存的写入在下一次读取时立刻可见

• CLI

本指南讲解 Himalaya（CLI 邮件客户端）在 pimdir 后端上实现的"队列可见性"能力：当一次离线写入（打标记、删除、移动、复制、更新、新建邮件）只进入同步队列、尚未被同步引擎应用时，Himalaya 如何让下一次读取就反映出这次写入，而不是把用户晾在"操作了却没反应"的窗口里。读完本文，你将理解PimdirReader叠加层的原理、Envelope.id为何保持String、以及himalaya pimdir queue list / cancel两个子命令的完整用法与源码实现。

问题背景：写入与读取之间的"失联窗口"

pimdir-producer-reader变更让 Himalaya 同时成为 pimdir 存储的读取者（reader）与生产者（producer）：一次写入是"往队列里追加一个动作"，一次读取是"对已提交索引的投影"，而两者之间没有任何连接。结果是：

• 给一封邮件打上标记，标记立刻从列表里消失；
• 移动一封邮件，它原地不动；
• 删除一封邮件，它还在列表里。

什么都不会丢，下一次同步后变更会如期落地。但在同步窗口期内，Himalaya 展示的是一个与用户刚刚执行的操作相矛盾的状态。如果被当成 bug 来读，这看起来就像数据丢失——对于一个以 GB 计量的邮件存储来说，这是最糟糕的误读。

其实存储格式早就预留了这个能力：pimdir 规范 §15.4 允许读取方把集合的待处理动作叠加到其投影之上，而PimdirProducer::pending_actions已经把队列行交给了调用方。Himalaya 只是从未调用它而已。本变更（cairn/changes/pimdir-queue-visibility/，落地于 2026-08-27，变更任务清单）补上了这一环，全部 18 项任务均已勾选完成。

为什么不直接"排空队列"：这不是答案

最直觉的修复是让 Himalaya 自己把队列里的动作排空（drain）应用到索引上。但设计文档明确否定了这条路，原因值得记录以免日后再被提起：

• 队列行没有source列，排空者必须自己盖上来源戳（stage_action从一个PimdirSourceStore取 source）；
• 绑定关系以(collection, link_id, source)为键；
• 任何非同步引擎的排空者，都会把变更以一个没有进程会推送的 source 暂存进去，静默失效；
• Himalaya 自pimdir.source被pimdir.account取代后，根本没有任何 source 可盖，即使理论上也无法正确排空。

所以 Himalaya 保持"读取者 + 生产者"的定位不变，队列由存储的所有者（同步引擎 Neverest）排空。

核心机制一：读取走叠加层，已暂存写入立即可见

PimdirClient不再直接持有存储句柄，而是持有叠加了队列的PimdirReader，并且用with_pending()构建（client.rs）：

// src/pimdir/client.rs let store = PimdirReader::open(&root) .map_err(|err| anyhow!("Open pimdir store `{}`: {err}", root.display()))? .with_pending();

叠加层覆盖五类针对已存在条目的动作：set-flags、update、remove、move、copy。这五类动作都保留条目的seq（公共 id），因此：

• 一次暂存的写入改变的是"列表显示什么"，绝不会改变"邮件如何被寻址"；
• Envelope.id仍然是String，消息寻址机制零变化。

对应到行为层面（delta.md 中的验收场景）：

• 离线打标记仍然保留：对无同步在排空的 pimdir 账户加一个标记并重新列出，邮件携带该标记；
• 离线删除立刻消失：删除一封邮件并重新列出，它从列表消失，动作仍留在队列中等所有者应用。

而停放（parked）的动作不得显示为已暂存：它不经操作员就不会被应用，显示为 pending 等于作出虚假承诺。

核心机制二：排队中的新建邮件"被报告，而不是被列出"

一个排队中的新建邮件（create）在所有者应用之前没有seq，也就没有可以放进信封的 id。发明一个占位 id（0、空字符串、q前缀令牌）等于把"什么都不指代的值"放进每个命令都会读回的那个字段。add_message已经返回它暂存时的 link id（即裸Message-ID，见 backend.rs），这正是跨窗口期识别一次新建的身份。

因此 Himalaya 采取如下策略（backend.rs）：

• 绝不把排队中的新建投影成信封；
• 绝不向Envelope.id填入占位符——它保持String，排队的信封 id 为空字符串；
• 信封列表报告它：一个有待处理新建的邮箱，会在表格下方打印类似N queued messages, see \himalaya pimdir queue list`的提示（[list.rs](https://link.gitcode.com/i/cedee2eedb12120e262d60d0230af82a)），并序列化进--json` 输出。

Envelopes携带queued计数字段；其他所有后端此值恒为0——这些后端的写入是即时到达服务器的，0才是真相。该字段因此保持"最小公分母"语义，而不是 pimdir 专属的旁支信息。

envelope search则一律报告queued: 0（search.rs）：排队中的新建永远不会被匹配进查询，而一个过滤器从未见过的计数只会比没有计数更糟。

用户困惑的时刻是"保存之后列表里没看到"，而不是保存当时，因此列表下方的报告才是真正防止"丢信"工单的环节。

实战命令一：himalaya pimdir queue list

新建的邮件和待发送的邮件在同步引擎应用之前没有 id，envelope list无法展示它们。pimdir操作员 CLI 是类型无关的，刻意只打印 id、哈希和标记；而 Himalaya 持有 blob 和邮件约定，可以读出发件人、主题、收件人，并依据行的created_at显示排队时长。

命令位于 src/pimdir/queue/list.rs，通过PimdirCommand→PimdirQueueCommand派发（cli.rs、queue/cli.rs，list带ls别名），接受一个MailboxArg（即-m）：

$ himalaya pimdir queue list -m imap/INBOX

输出表格包含六列（list.rs）：

空队列时打印No message queued in this mailbox；有行时在表格下方附注：Queued until the next sync. Cancel one with \himalaya pimdir queue cancel ``。

带--json时输出PimdirQueuedMessages（messages数组，每项含id、queued_at、producer、send、envelope），该类型已登记进 json_schema.rs（键名himalaya-pimdir-queue-list）。

注意：暂存的 flag、move、删除不需要这个视图——它们寻址的是已存在的消息，普通列表已经反映了它们。只有 create/send 这类"还没有消息可寻址"的动作才需要排队视图。

实战命令二：himalaya pimdir queue cancel <ROW>

取消是排队中的新建唯一的撤回途径：暂存的标记或移动可以通过"做相反操作"来撤销（set-flags是绝对值替换而非增量），但一封尚不存在的消息无法被删除。命令定义在 src/pimdir/queue/cancel.rs：

$ himalaya pimdir queue cancel <ROW>

行为要点：

• 取一个ROW位置参数（i64，即queue list打印的行 id），除非带--yes（短-y），否则先交互确认Cancel the message queued as row N?，拒绝则报Cancellation aborted（cancel.rs）；
• 内部通过 io-pimdir 的作用域化所有者操作PimdirStore::cancel_action完成（client.rs）。所有者角色只在这一次调用内进入并释放，Himalaya 永远不持有能排空队列或收集存储的句柄；
• 若行不存在，报No queued action with row N; it may have been synced already；
• 成功时输出Queued message N cancelled，JSON 输出为PimdirQueueCancelled（json_schema.rs，键名himalaya-pimdir-queue-cancel）。

同步期间的取消：快速失败且说人话

取消是存储所有者的写操作。若一个同步正在排空存储，所有者角色被占用，取消会立即失败，而不是等待锁：

A sync is running on `...`, so the queue cannot be edited; the action may have been applied already

（PimdirError::Owned被映射为该消息，见 client.rs。）快速失败在此是正确的：动作仍在队列里，等用户读到消息时它可能已被应用。消息直接说明"同步在跑、动作可能已应用"，而不是抛出一个费解的锁错误。对应 delta 场景"取消一行后行消失、正文留给收集器、邮箱不再报告排队消息"以及"同步期间取消立即失败"。

错误消息的边界约定

任何接受公共消息 id 的命令，若被问及一个排队中的新建，应拒绝并指明 cancel 命令，而不是报告"消息不存在"。message save则保持其通用确认文案不变——共享命令不会因后端不同而改变措辞。

配置侧：接入 pimdir 存储

队列可见性依托的 pimdir 配置位于 config.sample.toml，核心两行：

# 存储目录（Neverest 写入，含 pimdir.db 和 objects/） pimdir.root = "~/.local/state/neverest/example" # 多个账户共享同一存储时点名账户；单账户存储可留空 pimdir.account = "posteo"

两个影响队列使用的别名：

# 邮箱即集合 id 原样：服务器叫 INBOX 的邮箱在这里是 imap/INBOX mailbox.alias.inbox = "imap/INBOX" # 发送的邮件排队给所有者发送，存入 --save 指定邮箱或这里 mailbox.alias.sent = "imap/Sent"

注意客户端打开存储是只读的：PimdirClient::new要求pimdir.db已存在（"checkpimdir.root, and run a sync to create one"，client.rs），读取持有无锁的 reader 角色，写入只为一次入队短暂打开 producer。

上游缺陷与本变更的依赖

叠加层暴露了 io-pimdir 的一个上游缺陷：被叠加的页在集合中间可能"回短"——暂存的删除会去掉语句已返回的行。scan_items像所有 keyset 分页消费者一样，遇到短页即停止，于是一次暂存删除就可能提前结束整集合扫描，静默丢弃其后所有消息。该缺陷在 io-pimdir 的overlay-page-is-total修复中先行解决（任务清单首项io-pimdir reader-role and overlay-page-is-total, patched to git），本变更依赖该修复。

测试与验证

backend.rs 中的测试直接验证队列可见性的两个核心行为：

• a_queued_creation_renders_as_mail_with_no_id（L791-L817）：排队的新建渲染为邮件——主题Re: lunch、收件人alice@x.org、Message-IDdraft@x.org、标记\Draft均从动作钉住的正文摘要读出，且envelope.id为空；
• only_a_queued_creation_renders_as_mail（L819-L833）：仅新建会渲染进队列视图，暂存的删除寻址已存在的消息、普通列表已反映，故此处无内容。

另有a_sent_message_is_one_submit_row_with_its_envelope验证submit动作的v: 1载荷与排队视图联动。变更落地时测试全绿。

延期项：Envelope.id: Option<String>是 v1 的问题

排队中的新建是否该进message list，被明确判定为 v1 的问题（proposal.md 的 Deferred 一节）。若答案是肯定的，改动是Envelope.id: Option<String>，以null表示"尚无 id"——这是诚实且增量的编码。但在草稿箱 UX 明确要求之前，不值得为每个后端加宽共享信封结构。

小结

本变更把一个"看起来像数据丢失"的同步窗口，变成了三种清晰可读的状态：已暂存的针对已有邮件的动作立即反映在列表（叠加层）、排队中的新建以计数形式被报告而非被伪造列出（queued计数 + 空 id）、操作员可以通过queue list / queue cancel查看并撤回排队的新建与发送。它不排空队列（没有 source 可盖）、不进入所有者角色（只在取消瞬间借用）、不给Envelope.id塞占位值，全部设计都在 delta.md 与 实现日志 中留下了明确的验收场景与边界理由，是研究 Himalaya 如何优雅处理"客户端写入与同步引擎落库之间的时间差"的最佳入口。

• CLI