Fresh 单收件人 Mailbox 融合快路径 Delta¶

日期：2026-08-24
状态：实现、独立复核、真实 Redis 回归与短压 A/B 已完成；发布性能门禁仍未通过

变更摘要¶

为 standalone Redis 的最窄热态增加一次 Lua 调用的物化路径：当规范 manifest 恰有一个 canonical final chunk、该 chunk 恰有一个用户且只生成一个完整事件组时，脚本在首次写入前验证全部状态，并原子写入 DispatchProgress（DP）、邮箱条目及保留证明、完成索引和 64 lane packed watermark（W）。不满足适用条件、DP 已存在或无法完整证明热态时，接口返回 None 且零写，继续既有通用链路；脚本/状态错误返回 Err，该 record 必须停止，绝不降级为通用链路。

范围与非目标¶

项目	本 Delta 的行为
Redis 部署形态	仅 production 已明确支持的 standalone Redis，启动前必须由 `INFO server` 严格证明 `redis_version >= 7.0.0`。
Redis Cluster	不是支持 Cluster。 M-REDIS-04 仍 fail-closed；本 Lua 同时访问 `{shard}` DP/W 与 `{tenant:user}` mailbox keys，未来若支持 Cluster，必须另行设计事务/键槽架构。
适用 dispatch	精确一个 manifest chunk、该 chunk 是 canonical final、唯一收件人、唯一 `Entry`。多用户、多 chunk、零 chunk 走通用链路。
DP 身份	仅 DP key 完全不存在的 Fresh。DP 存在（无论 identity）在任何写入前返回 `None`；Existing、partial 和冲突继续通用链路。
邮箱保留状态	仅空 user key 空间，或 V4 热态：`active_day_count=1`、`min_day=max_day=entry day`、active-days zset 仅该 day、该 day 的 expiry/proof 严格一致。同日可有任意既有 seq。
排除状态	legacy、迁移、promotion、过期日、跨日活动范围或不能完整证明的状态，一律在写前 `None`；wrongtype、损坏、identity 缺失、future day/expiry、非法输入一律 `Err`。DP 已被 replay-safe GC 而同日 candidate identity 仍存在时也返回 `None`，由通用链路安全重建/覆盖事件组。

接口与集成点¶

MailboxStore 增加机会型的聚合方法 try_materialize_fresh_single_recipient。默认实现固定 Ok(None)，不进行任何写入，因此 Memory/Scylla 及测试替身仍保持既有语义。输入包含已经由 MailboxNode 验证的 single-recipient dispatch、mailbox_seq=0 的唯一 entry 模板，以及从接管快照取得的完整 64 lane expected-previous；成功结果返回 canonical receipt 和 64 lane 结果。

materialize_with_watermark_cache 在现有 begin_dispatch 前完成结构判定并调用该方法：

接管 W cache snapshot
  └─ 合格 single recipient？
       ├─ Some：更新同一 cache，构造 volatile output，返回（不调用 begin/append/finish）
       ├─ None：原有 begin → append/完成 chunk → finish 链路
       └─ Err ：停止本 record，cache 不更新，不 fallback

Redis override 使用自身配置的 epoch 将 entry 模板的 canonical mailbox_seq 设为 (current epoch, observed offset)，随后在 Rust 内确定性编码；Lua 仅验证该 bytes 的 sequence 前缀及其余参数的一致性，不重新解释业务 entry。MailboxNode 不从可能全空的 W cache 推断 epoch，也不为此新增远程读取。

原子事实与验证顺序¶

新 Lua 的所有 TYPE、格式、identity、expiry、V4 proof、DP 不存在、64 lane packed-v1 和 CAS 验证都位于首次写命令之前。成功时在同一脚本内写入：

v2 DP：64 个 m:<lane> 字段、期望/完成/剩余计数 1/1/0、canonical final、完成时间、 last_seen、max_observed；
dpcomplete:{shard}；
单 entry 的当天 mailbox zset、V4 meta、identity 索引及 active-day proof，全部使用既有固定绝对 EXPIREAT 规则（相同 day 只会重设同一 expiry，不延长 retention）；
wm:{shard} 的 packed-v1 blob，64 lane 按现有 CAS 语义推进。

脚本成功后不得再进行会导致逻辑失败的检查。若 EVAL 已成功而响应丢失，上层把该 record 作为失败停止；重放时 DP 已存在，快路径 None，通用 Existing 链路读取 final-complete DP 并收敛，不会重复事件组。

风险与防线¶

风险	防线
错把部分/历史状态当热态而混写	热态证明逐字段严格校验；无法证明只 `None`。
Lua 在错误后留下半事实	所有可失败验证和 key type 检查先完成；测试以字节级快照断言零写。
64 lane cache 与持久 W 分叉	只在返回完整成功结果后更新 cache；`Err`/`None` 均不更新。
响应丢失造成重复 entry	成功后 DP 已存在使重放转入现有 Existing 收敛路径。
Cluster 跨槽误解为已支持	文档和代码注释显式限于 standalone；既有 Cluster 拒绝门禁不变。
Lua 命令/ACL 与部署版本不符	启动门禁在任何 unsafe-dev 放宽前要求 Redis ≥7.0.0；部署 ACL 必须允许现有 Lua 所用命令（含 `EXPIRETIME` 及其他既有脚本使用的 Redis 7 条件过期选项）。本快路径写后只使用无选项的绝对 `EXPIREAT`。运行期 ACL 变更/Redis 进程级错误仍由脚本失败闭合，不在热路径逐条预检。

验收计划¶

能力与边界¶

Must Have	验证
Fresh 成功恰一次 EVAL 语义	真实隔离 Redis 校验 DP、唯一 entry、`dpcomplete`、V4 proof 和 64 packed W。
同日已存在 V4 热态仍成功	第二个 Fresh user record 同日写入，保留证明和身份索引保持一致。
已有 DP 零写退回	字节级快照证明 `None` 不改变任何 key。
响应丢失重放收敛	首次成功后重放经通用 Existing，只有一个事件组且 W 收敛。
CAS 与 key/type 损坏 fail-closed	CAS gap、每类 wrongtype、meta/identity 损坏、legacy、跨日/过期/future 分别断言 `Err` 或 `None`；每例都对 DP、completion、mailbox、meta、identity、active-days、W 共 7 key 的 `(DUMP, EXPIRETIME)` 前后完全相等。
MailboxNode 不误用快路径	fake store 证明 `Some` 不调用 begin/append/finish，`None` 调用完整通用链，`Err` 不 fallback 且不更新 cache。

禁止区¶

不修改通用 begin_dispatch、Existing 或 partial 恢复语义。
不在不合格输入上尝试“部分融合”或预写 DP。
不将跨 hash tag Lua 解释、测试或宣传为 Cluster 支持。
不为快路径引入新依赖、额外 Redis 往返或本地时间判定。

实际验证环境¶

使用 redis-server 启动在非 6379 的临时独立端口和临时目录，测试进程仅连接该实例的 DB 15；结束后精确关闭该 PID 并删除该临时目录。随后运行 qstore/qmailbox 定向测试、fmt、严格 clippy、契约检查与 diff 检查。

实际结果：

cargo test -p qim-common --lib：86/86；真实 standalone Redis 版本门禁：1/1。
cargo test -p qim-store --lib：52/52；隔离 Redis redis_store：38/38。
cargo test -p qim-mailbox --bin qim-mailbox：50/50。
cargo clippy -p qim-common -p qim-store -p qim-mailbox --all-targets -- -D warnings、 cargo fmt --all -- --check、scripts/check-contract.sh、git diff --check 均通过。
独立复核发现并关闭了两项边界：Redis 版本/写后命令半事实风险，以及 None/Err 测试未覆盖全部关联 key TTL。最终零写矩阵对 7 个 key 同时比较 (DUMP, EXPIRETIME)。

真实短压 A/B¶

以下均为隔离 Redpanda、core/mailbox split Redis、100 客户端、1000 msg/s、10 秒、 phase-stagger、64 shard、inflight=16；两组都精确提交 10000 条，frame/SDK 覆盖 100%，功能失败为 0。短压只用于定位，不能替代 180 秒发布门禁。

指标	融合前 `X8ItRX`	融合后 `BqdY36`	变化
Mailbox `EVALSHA` 次数	32939	11839	-64.06%
`EVALSHA` / materialized dispatch	3.1385	1.1281	-64.06%
Mailbox Lua 累计时间	8.883 s	7.623 s	-14.19%
Mailbox Redis CPU	10.316 s	8.815 s	-14.55%
materialize 均值	15.47 ms	11.83 ms	-23.52%
permit 均值	16.38 ms	9.18 ms	-43.94%
shard queue 均值	545.04 ms	43.84 ms	-91.96%
ACK P99	9.5 ms	9.5 ms	持平
E2E P99	3052.5 ms	732.0 ms	-76.02%

工件：

融合前：/tmp/qim-artifacts.qim-it-u1000-1787541564-1840597.X8ItRX
融合后：/tmp/qim-artifacts.qim-it-u1000-1787545352-1947826.BqdY36

该结果强烈支持“典型 Fresh 热路径约三次脚本收敛为约一次”的总体效果，但工件没有按脚本 hit/miss counter，不能声称每一条 dispatch 都命中，也不能从聚合 EVALSHA 精确恢复命中率。 E2E P99 仍高于 300 ms，因此本 Delta 的功能与局部性能目标已达成，项目发布性能 Todo 未完成。