Himalaya pimdir 队列可见性：让暂存写入在下一次同步前即时可见

• CLI

导读

本文以 Himalaya 项目中pimdir-queue-visibility变更提案（cairn/changes/pimdir-queue-visibility/proposal.md）为骨架，剖析 pimdir 离线缓存后端“写入进队列、读取看索引”分离后遗留的可见性缺口，以及 Himalaya 如何通过叠加读取（overlay）、排队计数报告与**pimdir queue子命令**三件套将其补齐。读完本文，你将理解：暂存的set-flags/remove/move/copy/update为何能立即反映到列表，排队的创建消息为何“报告而不列出”，以及如何用himalaya pimdir queue list查看、用queue cancel撤回一条尚未被同步引擎应用的排队消息——包括为什么“排空队列（draining）”在这里不是正确答案。

问题缘起：写入与读取之间隔着一整条同步队列

pimdir-producer-reader变更让 Himalaya 同时成为 pimdir 存储的读者（reader）与生产者（producer）：写入被“暂存（stage）”为追加到存储队列中的动作（action），读取则是已提交索引（committed index）的投影。这两者之间原本没有任何连接——于是出现了一个让用户恐慌的窗口期：

给一封邮件打上旗标，列表里旗标立刻消失；移动一封邮件，它停留在原处。数据什么都没丢，下一次同步后变更会落地，但在这段窗口期内，Himalaya 报告出的存储状态与用户刚刚执行的操作互相矛盾。

对一个以 GB 计的邮件存储来说，这种矛盾被用户读作“数据丢失”——这正是一个邮件客户端能收到的最糟糕的误读（proposal 原文称之为 "the worst reading available"）。

值得强调的是，这一缺口并非架构设计上的意外：pimdir SPEC §15.4 早已允许读取方把某个集合的待处理动作（pending actions）叠加（overlay）到其投影之上，而PimdirProducer::pending_actions也已能给出这些行——只是 Himalaya 从未调用它。本变更的实质，就是把规范预留的能力真正接入客户端读取路径。

为什么“排空队列”不是答案

在给出修复方案之前，提案专门用一段写明了为什么不能靠 Himalaya 自己排空队列，以免该方案被再次提出：

• 队列行没有 source 列：排空方（drainer）需要自己盖上来源（stage_action从PimdirSourceStore取 source）；
• 绑定（bindings）以(collection, link_id, source)为键；
• 一旦排空方不是同步引擎，就会把变更以“没有任何东西会推送的 source”暂存出去——静默失败；
• 而 Himalaya 在pimdir.source被移除后，连可以盖的 source 都没有，所以即使在原理上也无法正确排空。

结论明确：Himalaya 保持“读者 + 生产者”的定位，把排空和应用交给存储的所有者（同步引擎，日志中称为 Neverest）。这也是queue cancel为何必须走“所有者（owner）作用域操作”的根本原因——撤消一个排队动作是所有者才有的写权限。

修复方案一：读路径叠加待处理动作

核心改动集中在 src/pimdir/client.rs：PimdirClient不再持有普通 store 句柄，而是持有一个叠加了待处理动作的PimdirReader：

// src/pimdir/client.rs#L56-L60 // NOTE: reads overlay the queue, so what this client staged shows on // the next read rather than on the next sync. let store = PimdirReader::open(&root) .map_err(|err| anyhow!("Open pimdir store `{}`: {err}", root.display()))? .with_pending();

with_pending()让五种针对已存在消息的动作在下次读取时立即可见：

关键在于：这五种动作都保留了消息的seq，因此“消息如何被寻址”没有任何变化，Envelope.id依旧是一个String——叠加只改变列表显示什么，绝不改变消息如何被寻址（"a staged write changes what a listing shows and never how a message is addressed"）。

需求方（delta.md）还明确了一条边界：停放（parked）的动作不得显示为已暂存——它没有操作者就不会被应用，按“待处理”读取等于向用户许诺做不到的事。

修复方案二：排队创建“报告而不列出”

set-flags、remove、move、copy、update都有现成的消息可寻址，但一条排队中的创建（queued create）没有seq——在同步引擎（所有者）应用它之前，它不存在于索引中，也就没有 id 可以放进信封（envelope）。

提案明确否决了三种“发明 id”的做法：

• 0或空字符串：它们是标识符空间内的取值，却什么也不命名；
• q前缀的令牌：这是另一个空间的 id，却要被塞进每个命令都会读回的字段里。

所以排队创建不是被投影成信封，而是被报告出来。add_message已经返回它暂存时的 link id——这才是跨越整个窗口期标识一条创建的正确句柄。

落到实现上，src/shared/envelope/list.rs 的Envelopes结构新增了queued: usize字段（L175），在表格下方渲染为：

N queued messages, see `himalaya pimdir queue list`

（见 L245-L251 的实现：0时不输出，1时输出单数形式，其余输出复数。）该字段同样参与--json序列化。对其他所有后端而言该值恒为 0——它们的写入即时到达服务器，0 才是事实，因此这个字段是“最小公分母”而非 pimdir 专属的琐碎细节。

两个细节值得注意：

• envelope search一律报告 none（src/pimdir/backend.rs 的search_envelopes，L155-L176）：排队创建从不参与查询匹配，一个过滤器从未见过的计数比没有计数更糟；
• 计数出现的时机是“用户正困惑的那一刻”——列表里没有刚保存的消息——而不是保存那一刻，因此它真正阻止了问题报告的产生。

修复方案三：himalaya pimdir queue list—— 把排队创建渲染成邮件

pimdir 的操作者 CLI 是**类型无关（kind-agnostic）**的，只会打印 id、哈希和旗标；而 Himalaya 持有 blob 与邮件约定，可以做得更多。pimdir queue list命令把排队创建渲染成真正的邮件视图。

命令树（src/pimdir/cli.rs、src/pimdir/queue/cli.rs）：

himalaya pimdir queue list # 别名 ls：列出某邮箱排队的创建与发送 himalaya pimdir queue cancel <ROW> # 撤回一行，确认后执行（除非 --yes）

list的实现（src/pimdir/queue/list.rs）以MailboxArg定位邮箱，调用PimdirClient::queued_envelopes(&mailbox)，输出一张六列表格：

关键字段（PimdirQueuedMessage，L78-L92）：

• id（i64）：队列行 id，命名的是待处理动作而非消息——消息在被同步引擎应用前没有 id，应用后也会得到另一个不同的 id；
• queued_at：行被追加的时刻，来自存储自身的时钟——即“年龄”的来源；
• producer：暂存它的进程名（本仓库恒为himalaya）；
• send：该行是发送（send）而非归档（save）；
• envelope：从动作钉住的 blob 中重新推导出的摘要，其id为空（排队消息尚无 id）。

空队列输出No message queued in this mailbox；非空时表格尾部附一行引导：

Queued until the next sync. Cancel one with `himalaya pimdir queue cancel <ROW>`

表格样式（预设、各列颜色、未读/回复/旗标字形）全部复用账号的envelope list配置（table_preset、envelopes_list_table_*等），与普通列表观感一致。

修复方案四：himalaya pimdir queue cancel <ROW>—— 唯一的撤回通道

src/pimdir/queue/cancel.rs 的PimdirQueueCancelCommand接收两个参数：

/// Row id of the staged message, as `pimdir queue list` prints it. #[arg(value_name = "ROW")] pub id: i64, /// Do not ask for confirmation. #[arg(long, short)] pub yes: bool,

执行流程：

1. 除非--yes，否则弹出布尔确认（Cancel the message queued as row {id}?），拒绝则Cancellation aborted；
2. 调用PimdirClient::cancel_queued(id)，经 io-pimdir 的作用域化所有者操作（scoped owner operation，对应 pimdir SPEC §15.5）撤回一行；
3. 成功输出Queued message {id} cancelled；若行已不存在，报No queued action with row {id}; it may have been synced already。

cancel_queued的实现（src/pimdir/client.rs#L99-L108）体现了三条设计约束：

pub fn cancel_queued(&self, id: i64) -> Result<bool> { PimdirStore::cancel_action(&self.root, id).map_err(|err| match err { PimdirError::Owned(_) => anyhow!( "A sync is running on `{}`, so the queue cannot be edited; \ the action may have been applied already", self.root.display(), ), err => anyhow!("Cancel queued action {id}: {err}"), }) }

• 角色最短持有：所有者角色只在这一次调用内进入并释放，Himalaya 从不持有能排空队列或收集存储的句柄；src/pimdir/backend.rs 的读写路径也绝不触碰所有者角色；
• 同步期间快速失败（fail-fast）：另一进程（同步引擎）正在排空存储时，立即拒绝并说明“同步正在进行、动作可能已被应用”，而不是抛出一个锁错误——因为动作仍在排队，用户读到消息时它可能已经被应用了；
• message save的确认文案不变：共享命令的措辞不因后端而异（proposal 明确 "The shared commands do not vary their wording by backend"）。

此外，delta 需求还规定：一个接受公开 id 的命令，如果被问及一条排队创建，应当拒绝并点名 cancel 命令，而不是报告“未知消息”。

从需求到验证：测试与落地记录

变更需求（delta.md）以场景形式固化了验收标准：

• 离线加旗标后仍在：对无同步排空的 pimdir 账号加旗标并重新列出 → 消息带着旗标；
• 离线删除后离开列表：删除消息并重新列出 → 它从列表消失，动作仍在队列中等待所有者；
• 保存的消息说明去向：向 pimdir 邮箱保存消息且尚未同步 → 列表不新增信封，但报告“1 queued message”并点名himalaya pimdir queue list；
• 撤回排队的草稿：对未被同步应用的排队创建执行queue cancel→ 行消失，正文留给收集器（collector），邮箱不再报告排队消息；
• 同步期间撤回：Neverest 正在排空存储 → 撤回立即失败，说明同步正在进行、动作可能已被应用。

实现层面的测试位于 src/pimdir/backend.rs（如a_sent_message_is_one_submit_row_with_its_envelope，L852-L897，以及“排队创建渲染为带空 id 的邮件”“只有创建动作出现在队列视图，暂存的删除因寻址已存在的消息而无从渲染”），对应的任务清单见 tasks.md。落地日志 2026-08-27-pimdir-queue-visibility.md 记录：118 个测试全部通过，且变更期间在 io-pimdir 上游发现并依赖其修复了一个缺陷overlay-page-is-total——叠加页可能在集合中间提前变短（暂存删除会从已返回结果中抽走一行，导致基于 keyset 分页的全集合扫描提前终止、静默丢弃后续消息），本变更因此依赖该上游补丁。

延后事项：Envelope.id保持String

提案明确将“排队创建是否该进入message list”判定为v1 问题：若答案是肯定的，届时采用Envelope.id: Option<String>，以null编码“尚未分配 id”——这是诚实的编码，也是纯增量的改动。但在草稿 UX（drafts UX）证明有必要之前，不值得为所有后端拓宽共享信封结构。

小结

pimdir-queue-visibility变更把 Himalaya 的 pimdir 后端从一个“与用户操作脱节”的只读投影，变成了一套自洽的读写体验：

1. 读路径叠加（src/pimdir/client.rs 的PimdirReader::with_pending()）让针对存量消息的五种暂存动作即时可见，且不改动消息寻址方式、Envelope.id维持String；
2. 排队创建“报告而不列出”（src/shared/envelope/list.rs 的Envelopes.queued）在用户最困惑的时刻（列表里找不到刚保存的消息）给出解释并点名查看命令，把“数据丢失”误读扼杀在源头；
3. pimdir queue list/queue cancel（src/pimdir/queue/list.rs、src/pimdir/queue/cancel.rs）用邮件视图补上了“跨窗口期标识排队创建”的最后一块拼图，并以作用域化的所有者操作、同步期快速失败、确认提示（--yes跳过）完整定义了撤回的语义边界。

整套方案始终恪守一条原则：Himalaya 是读者和生产者，不越权成为排空者——把应用动作的权力留给存储的所有者，同时让用户在下一次同步之前就清楚地看到自己做过什么、这些东西去了哪里。

• CLI