merge: W21 — 重试记忆加 10 分钟时间上界（多槽不会跨小时误撞旧键）

app/src/main/kotlin/top/yeij/cyrene/domain/chat/RetryKeyMemory.kt

@@ -1,7 +1,16 @@
 package top.yeij.cyrene.domain.chat
 
-/** 一次「没发出去」留下的记录：**那一条**的内容指纹 + 当时铸的幂等键（`localId`）。 */
-data class RetryKeySlot(val fingerprint: MessageFingerprint, val localId: String)
+/**
+ * 一次「没发出去」留下的记录：**那一条**的内容指纹 + 当时铸的幂等键（`localId`）+ 记下它的时刻。
+ *
+ * [atMillis] 只服务于 [RetryKeyMemory.SLOT_TTL_MILLIS] 那道时间闸，与键本身的语义无关：没有它，一条
+ * 几小时前的失败记录会一直活着，用户**新**打的一句同内容的话就会被当成重试（见 [RetryKeyMemory]）。
+ */
+data class RetryKeySlot(
+    val fingerprint: MessageFingerprint,
+    val localId: String,
+    val atMillis: Long,
+)
 
 /**
  * [RetryKeyMemory.keyFor] 的判定结果：这一次发送该用哪个幂等键，以及记忆变成什么样。
@@ -12,7 +21,7 @@ data class RetryKeySlot(val fingerprint: MessageFingerprint, val localId: String
 data class RetryKeyDecision(val localId: String, val memory: RetryKeyMemory)
 
 /**
- * 「没发出去的那几条」的记忆——**多槽**、纯值、可单测。
+ * 「没发出去的那几条」的记忆——**多槽**、**有时间上界**、纯值、可单测。
  *
  * ## 它存在的理由
  * 幂等键要想真的挡住重复，就必须在**同一条消息**的两次发送之间保持不变。而「某次失败」并不
@@ -22,6 +31,24 @@ data class RetryKeyDecision(val localId: String, val memory: RetryKeyMemory)
  * 让「一模一样的内容再发一次」落回同一个键，由服务端用 `chat_duplicate` /
  * `{duplicate:true,messageId}` 替本端裁决。
  *
+ * ## 时间上界：10 分钟，为什么多槽必须配一个时钟
+ * 记录是**跨很多次发送**存活的（这正是多槽的意义，见下面「为什么是多槽」），于是有了一个单槽时代
+ * 不存在的窗口：用户**几小时前**失败过一句「你好」，之后**新**打一遍「你好」—— 他心里当的是一条
+ * **新**消息，指纹却与那条旧记录一字不差 ⇒ [keyFor] 命中 ⇒ 复用旧键 ⇒ 服务端回 `chat_duplicate`
+ * ⇒ 这条新消息**根本不发出去**，屏幕上看着像「按了没反应」。给每个槽加一道时间闸
+ * [SLOT_TTL_MILLIS]，这个窗口就被钉死在 10 分钟内；而真正需要幂等的那一幕 ——「刚失败完，用户马上
+ * 又按了一次发送」—— 一秒都没被削掉。
+ *
+ * 时钟由调用方喂（[remember] 的 `atMillis`、[keyFor] 的 `nowMillis`），纯值类型里**不藏**
+ * `System.currentTimeMillis()`：判据才可单测，也才不用为了「等 10 分钟」写 sleep。
+ *
+ * ## 边界口径：正好等于 TTL **不算**过期
+ * 判据是 `nowMillis - atMillis > SLOT_TTL_MILLIS`（严格大于），所以 `nowMillis == atMillis + TTL`
+ * 那一条**仍然命中**，真正过期要再晚一毫秒。选这一边的理由：常量自身就能当「仍在窗口内」的边界值
+ * 直接断言（测试不必为「还活着」那一侧发明魔法数），过期那一侧才需要显式的 `+1`；而真实时钟几乎
+ * 不可能精确落在这 1 毫秒上，口径选哪边都没有实害，可测的那边更有价值。测试
+ * `a slot exactly at the TTL boundary still counts as fresh` 把这条钉住。
+ *
  * ## 三条纪律
  * 1. **只在回滚时写**（[remember]：发送失败 / 队列满被拒 / 附件与图片上传失败 / 图片处理失败…）：
  *    被受理的那条没有任何要记的东西。
@@ -36,12 +63,19 @@ data class RetryKeyDecision(val localId: String, val memory: RetryKeyMemory)
  * 「服务端其实已经收下」的那条 B 落成**第二条**消息，正是本机制要消灭的重复。多槽让每条失败各留
  * 一个槽，用户重试哪一条就落回哪一条的键，与他的操作顺序无关。
  *
- * ## 上限与淘汰：FIFO，不是 LRU
+ * ## 上限与淘汰：条数上限 8 + 时间上界 10 分钟，两条规则同时生效
  * 一条记录只在「用户可能还要重试」的窗口里有意义：失败后正文 / 图片 / 附件都还回了输入栏，他要么
  * 马上原样重发、要么早就改了内容（那就成了另一条消息，记录永远命中不了）。窗口外留下的只是垃圾，
- * 所以给一个小上界 [MAX_SLOTS]，满了丢**最旧**的（[remember] 里 FIFO）。刻意**不**做 LRU：命中
- * 并消费是**轮询**而不是访问 —— [keyFor] 把命中的那条整个摘走，与它有多旧无关，谈「最近使用」没有
- * 意义；也正因如此，剩下的槽天然还是写入顺序。
+ * 所以有两把尺子：条数上限 [MAX_SLOTS]（满了丢**最旧**的，[remember] 里 FIFO）与时间上界
+ * [SLOT_TTL_MILLIS]（比上限还旧的那条，无论排第几都作废）。
+ *
+ * **顺序是死的**：[remember] / [keyFor] **先按时间淘汰**过期槽，再做自己那件事（去重追加 / 查命中），
+ * 写入时**最后**才看条数上限。先按时间清的好处是过期槽不占那份本该给新鲜记录的额度 —— 否则 8 个
+ * 早已过期的槽会把刚写进来的那条挤出去（或者更糟：让 [keyFor] 在一个条数已满、内容却全过期的记忆里
+ * 报「满了」）。
+ *
+ * 刻意**不**做 LRU：命中并消费是**轮询**而不是访问 —— [keyFor] 把命中的那条整个摘走，与它有多旧
+ * 无关（只要求没过期），谈「最近使用」没有意义；也正因如此，剩下的槽天然还是写入顺序。
  *
  * ## 与「绝不自动重试」不矛盾
  * 这里一个字节都不自动重发：复用键只发生在**用户自己又按了一次发送**、且内容一字不差的时候。
@@ -52,12 +86,20 @@ data class RetryKeyMemory(val slots: List<RetryKeySlot> = emptyList()) {
     /**
      * 记下「这一条没发出去」（回滚时调用）。
      *
-     * 同一个指纹**先摘掉旧的、再把新的追加到末尾**：同一条又失败一次是**更新**它的键，而不是并列
-     * 两条 —— 两条同指纹时 [keyFor] 只会命中更早那条，用户的重试反而用不上刚铸的键。超过
-     * [MAX_SLOTS] 就从头部丢最旧的：本函数最多让**末尾**那条变新，淘汰因此绝不会伤到刚写的这条。
+     * 三件事按固定顺序做，别调换（理由见类注释「上限与淘汰」）：
+     * 1. **先按 [atMillis] 淘汰过期槽**——[atMillis] 既是这条记录的出生时刻，也是「现在」；
+     * 2. 同一个指纹**先摘掉旧的、再把新的追加到末尾**：同一条又失败一次是**更新**它的键与时刻，
+     *    而不是并列两条 —— 两条同指纹时 [keyFor] 只会命中更早那条，用户的重试反而用不上刚铸的键，
+     *    而且那条更早的还会**先**过期（明明刚失败过，记录却已经超时，重试退回铸新键）；
+     * 3. 超过 [MAX_SLOTS] 就从头部丢最旧的：本函数最多让**末尾**那条变新，淘汰因此绝不会伤到刚写的
+     *    这条。
+     *
+     * @param atMillis 这次失败发生的时刻，由调用方喂（`System.currentTimeMillis()`）。
      */
-    fun remember(fingerprint: MessageFingerprint, localId: String): RetryKeyMemory {
-        val kept = slots.filterNot { it.fingerprint == fingerprint } + RetryKeySlot(fingerprint, localId)
+    fun remember(fingerprint: MessageFingerprint, localId: String, atMillis: Long): RetryKeyMemory {
+        val fresh = purge(atMillis)
+        val kept = fresh.slots.filterNot { it.fingerprint == fingerprint } +
+            RetryKeySlot(fingerprint, localId, atMillis)
         return RetryKeyMemory(if (kept.size > MAX_SLOTS) kept.takeLast(MAX_SLOTS) else kept)
     }
 
@@ -67,6 +109,10 @@ data class RetryKeyMemory(val slots: List<RetryKeySlot> = emptyList()) {
      * 一条都对不上就**原样返回同一个实例**（一条也不清）：槽里躺的多半是别的刚回滚的消息，顺手清掉
      * 它们会让那几条的重试退回「铸新键」。同一个 `localId` 万一有多条（[remember] 保证不会有），
      * 一并清掉：留着一条键已被服务端受理过的记录，只会让将来的某次重发被当成重复吞掉。
+     *
+     * **与时间无关**：受理回执说的是「这条键服务端认了」，无论它记于几分钟前。此处也不顺手扫过期槽
+     * —— 那要一个调用方没给的「现在」，而且过期槽本来就命中不了（[keyFor] 入口会清掉它们），留着
+     * 最多是几个死条目的内存占用。
      */
     fun forget(localId: String): RetryKeyMemory {
         val kept = slots.filterNot { it.localId == localId }
@@ -74,25 +120,58 @@ data class RetryKeyMemory(val slots: List<RetryKeySlot> = emptyList()) {
     }
 
     /**
-     * 这一次发送该用哪个幂等键：内容与某条记录一致 ⇒ **复用**它的键，并**只消费那一条**（其余槽
-     * 原样保留 —— 它们对应的是别的失败消息，正等着被各自的重试捡起来）；一条都对不上 ⇒ 铸一个新的
-     * （[mint] 由调用方给，测试才能喂确定性的键，也才能断言「该不该铸」），**且一条槽也不清**。
+     * 这一次发送该用哪个幂等键：内容与某条**未过期**的记录一致 ⇒ **复用**它的键，并**只消费那一条**
+     * （其余槽原样保留 —— 它们对应的是别的失败消息，正等着被各自的重试捡起来）；一条都对不上 ⇒
+     * 铸一个新的（[mint] 由调用方给，测试才能喂确定性的键，也才能断言「该不该铸」），**且一条槽也不清**。
+     *
+     * 入口**先**按 [nowMillis] 淘汰过期槽，过期的那条**视同不存在**：找不到就铸新键，与「从来没记过」
+     * 这条完全一样。这正是时间上界要挡住的那一幕（见类注释「时间上界」）—— 几小时前失败过的同内容
+     * 消息，今天再打一遍就是一条**新**消息，绝不能因为撞上旧键而被服务端当成重复吞掉。
      *
      * 最后这半句是与单槽时代最本质的差别，**别照着旧注释改回去**：那时记忆只有一条，「未命中就清空」
      * 与「保留」是同一件事；多槽下清空会把用户**别的**失败记录一并抹掉（他重试 A 时铸了新键，接着去
      * 重试 B，B 的槽已经没了 ⇒ 那次重发退化成非幂等）。未命中只说明「这次的正文没有任何失败记录对得
-     * 上」，不是「记忆都作废了」。
+     * 上」，不是「记忆都作废了」。（过期槽被摘掉不算例外：它们本来就再也命中不了。）
+     *
+     * @param nowMillis 这次发送的时刻，由调用方喂（`System.currentTimeMillis()`）。
      */
-    fun keyFor(fingerprint: MessageFingerprint, mint: () -> String): RetryKeyDecision {
-        val hitIndex = slots.indexOfFirst { it.fingerprint == fingerprint }
-        if (hitIndex < 0) return RetryKeyDecision(mint(), this)
+    fun keyFor(
+        fingerprint: MessageFingerprint,
+        nowMillis: Long,
+        mint: () -> String,
+    ): RetryKeyDecision {
+        val fresh = purge(nowMillis)
+        val hitIndex = fresh.slots.indexOfFirst { it.fingerprint == fingerprint }
+        if (hitIndex < 0) return RetryKeyDecision(mint(), fresh)
 
-        val consumed = RetryKeyMemory(slots.filterIndexed { index, _ -> index != hitIndex })
-        return RetryKeyDecision(slots[hitIndex].localId, consumed)
+        val consumed = RetryKeyMemory(fresh.slots.filterIndexed { index, _ -> index != hitIndex })
+        return RetryKeyDecision(fresh.slots[hitIndex].localId, consumed)
+    }
+
+    /**
+     * 摘掉在 [nowMillis] 这一刻已经过期的槽；一条都没过期就**原样返回同一个实例**（不必新建对象）。
+     *
+     * 过期判据见类注释「边界口径」——正好等于 [SLOT_TTL_MILLIS] 的那条**留着**。
+     */
+    private fun purge(nowMillis: Long): RetryKeyMemory {
+        val kept = slots.filterNot { it.isExpiredAt(nowMillis) }
+        return if (kept.size == slots.size) this else RetryKeyMemory(kept)
     }
 
     companion object {
         /** 同时保留的失败记录条数上限；淘汰策略见类注释「上限与淘汰」。 */
         const val MAX_SLOTS = 8
+
+        /**
+         * 一条失败记录最多活多久（10 分钟）：超过它，[keyFor] 就再也认不出这条记录。
+         *
+         * 公开是因为**测试拿它做断言**（别在测试里重写一遍 `10 * 60 * 1000L`，那样改口径时测试不会
+         * 跟着变）。为什么需要这道闸、边界怎么算，见类注释「时间上界」与「边界口径」。
+         */
+        const val SLOT_TTL_MILLIS = 10 * 60 * 1000L
+
+        /** 这条记录在 [nowMillis] 这一刻是否已过期；`>` 而不是 `>=`，见类注释「边界口径」。 */
+        private fun RetryKeySlot.isExpiredAt(nowMillis: Long): Boolean =
+            nowMillis - atMillis > SLOT_TTL_MILLIS
     }
 }

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ChatViewModel.kt

@@ -503,7 +503,9 @@ data class ChatUiState(
  * 幂等由 [MessageFingerprint] + [retryKey] 这一对承担：**回滚**时按内容指纹记下那条用过的
  * `clientMsgId`，用户**自己**再按一次发送、且内容一字不差时复用它（[emitAndDeliver] 是唯一的
  * 消费者）——服务端据此判重（`chat_duplicate` / `{duplicate:true}`）而不是落成第二条消息；
- * 内容改过（哪怕只多一个空格）就铸新键，因为那是另一条消息。**始终没有自动重试**：
+ * 内容改过（哪怕只多一个空格）就铸新键，因为那是另一条消息。记录**不是永久的**：每条只活
+ * [RetryKeyMemory.SLOT_TTL_MILLIS]（10 分钟，见那里「时间上界」）——多槽让记录跨很多次发送存活，
+ * 太久以前那条失败过的内容再打一遍是**新**消息，不能被当成重试吞掉。**始终没有自动重试**：
  * 键的复用只发生在用户手动重发的那一刻。
  *
  * ## 单条消息的编辑 / 删除（D3）
@@ -542,6 +544,12 @@ class ChatViewModel(
      * 刻意不清**：一条晚到的 `message_persisted` 恰恰是「服务端其实收下了、客户端当时判成失败」
      * 的证据，这时候把键留着，用户接下来的重试才会被判重而不是落成第二条消息 —— 那正是本机制
      * 存在的理由。
+     *
+     * 记录**有时间上界**（[RetryKeyMemory.SLOT_TTL_MILLIS] = 10 分钟）：比这还旧的槽在这一次发送时
+     * 视同不存在。没有这道闸，多槽会让几小时前失败过的记录一直活着，用户**新**打一遍同样的内容就
+     * 被服务端当成重复吞掉（看屏幕就是「按了没反应」）；而「刚失败完，用户马上再按一次发送」这个
+     * 真正需要幂等的场景一秒都没被削掉。时间由上面两个调用点喂（`System.currentTimeMillis()`），
+     * 这个纯值类型里不藏时钟。
      */
     private var retryKey = RetryKeyMemory()
 
@@ -844,7 +852,12 @@ class ChatViewModel(
         // 复用键会让服务端判重并回 `chat_duplicate` / `{duplicate:true}`，而不是落成第二条消息。
         // 内容不同（改过字 / 换图 / 动了附件）则铸新键——用户的编辑是一条**新**消息。
         // 消费只发生在命中那一支：命中的那条记录在这里被摘走，别的失败记录原样留着（见 [RetryKeyMemory]）。
-        val decision = retryKey.keyFor(MessageFingerprint.of(text, imageUri, documents)) {
+        // 「现在」由这里喂进去（纯值类型里不藏时钟）：记下超过 `SLOT_TTL_MILLIS` 的那条已经不可复用、
+        // 视同从来没记过——几小时前失败过同内容的消息，用户今天再打一遍是一条**新**消息。
+        val decision = retryKey.keyFor(
+            MessageFingerprint.of(text, imageUri, documents),
+            System.currentTimeMillis(),
+        ) {
             "local-${UUID.randomUUID()}"
         }
         retryKey = decision.memory
@@ -1172,7 +1185,10 @@ class ChatViewModel(
     }
 
     /**
-     * 把「这一条没发出去」记进 [retryKey]（指纹 + 当时用的幂等键）。
+     * 把「这一条没发出去」记进 [retryKey]（指纹 + 当时用的幂等键 + 记下的**时刻**）。
+     *
+     * 时刻由这里喂（`System.currentTimeMillis()`），它是 [RetryKeyMemory.SLOT_TTL_MILLIS] 那道时间闸
+     * 的起算点：同内容再次失败会把时刻一起刷新，所以「记得早」不会让一条刚更新的记录提前过期。
      *
      * 气泡**不在**待发列表里就什么都不记：那种情况下没有任何东西被回滚，记一条只会在下一次
      * 发送时凭空复用别人的键。传 [pending] 而不是自己读 `_state`，是因为调用点必须能在这条
@@ -1183,6 +1199,7 @@ class ChatViewModel(
         retryKey = retryKey.remember(
             MessageFingerprint.of(failed.text, failed.imageUri, failed.documents),
             localId,
+            System.currentTimeMillis(),
         )
     }
 

app/src/test/kotlin/top/yeij/cyrene/domain/chat/RetryKeyMemoryTest.kt

@@ -11,7 +11,7 @@ import top.yeij.cyrene.ui.chat.QueueFullOutcome
 import top.yeij.cyrene.ui.chat.applyQueueFull
 
 /**
- * 重试记忆：幂等键什么时候**复用**、什么时候**重铸**、什么时候**被清**。
+ * 重试记忆：幂等键什么时候**复用**、什么时候**重铸**、什么时候**被清**、什么时候**已过期作废**。
  *
  * 这是本模块要修的那条「文档与实现不符」的判据所在：`PendingMessage` 的 KDoc 一直写着「重试复用
  * 同一个 id」，而实现每次发送都铸新键 —— 于是「服务端其实已经收下、客户端判成失败」（队列满 /
@@ -23,7 +23,13 @@ import top.yeij.cyrene.ui.chat.applyQueueFull
  *    也要清空」是对的（那时只有一条），多槽下照抄会把用户**别的**失败记录一起抹掉，那些重发就
  *    退化成非幂等；
  * 3. 只有这一条能清的清得掉、别的条清不动（否则几条同时在飞时会互相踩）；
- * 4. 满了按 FIFO 丢最旧的，**且绝不丢刚写进去的那条**。
+ * 4. 满了按 FIFO 丢最旧的，**且绝不丢刚写进去的那条**；
+ * 5. 每条记录只在 [RetryKeyMemory.SLOT_TTL_MILLIS] 内有效 —— 多槽让记录跨很多次发送存活，没有这道
+ *    时间闸，几小时前失败过的同一句话再打一遍就会被当成重试（服务端判重 ⇒ 新消息根本不出去）。
+ *    过期槽**视同不存在**并被淘汰，而**正好等于 TTL 不算过期**（判据是严格大于，见
+ *    [RetryKeyMemory] 的「边界口径」与下面 `... exactly at the TTL boundary ...` 那条）。
+ *
+ * 时间一律由测试喂进去（[t0] 起算），所以判据确定、也不必为了「等 10 分钟」写 sleep。
  */
 class RetryKeyMemoryTest {
 
@@ -35,6 +41,15 @@ class RetryKeyMemoryTest {
         fun next(): String = "new-${++count}"
     }
 
+    /** 失败发生的基准时刻；所有时间断言都相对它写，测试里不出现裸的「10 分钟」。 */
+    private val t0 = 1_700_000_000_000L
+
+    /** 刚好卡在边界上：`t0 + TTL` 这一毫秒**还没**过期。 */
+    private val atTheBoundary = t0 + RetryKeyMemory.SLOT_TTL_MILLIS
+
+    /** 过了边界一毫秒：从这一刻起，记于 [t0] 的槽作废。 */
+    private val pastTheBoundary = atTheBoundary + 1
+
     private val text = MessageFingerprint.of("你好", null, emptyList())
 
     private val edited = MessageFingerprint.of("你好！", null, emptyList())
@@ -44,10 +59,12 @@ class RetryKeyMemoryTest {
     private fun doc(uri: String) = DraftDocument(uri = uri, displayName = "a.txt", sizeBytes = 1L)
 
     /** 按失败发生的先后逐条 `remember`（与 `ChatViewModel.rollback` 的调用顺序一致）。 */
-    private fun failed(vararg records: Pair<MessageFingerprint, String>): RetryKeyMemory =
-        records.fold(RetryKeyMemory()) { memory, (fingerprint, localId) ->
-            memory.remember(fingerprint, localId)
-        }
+    private fun failed(
+        vararg records: Pair<MessageFingerprint, String>,
+        atMillis: Long = t0,
+    ): RetryKeyMemory = records.fold(RetryKeyMemory()) { memory, (fingerprint, localId) ->
+        memory.remember(fingerprint, localId, atMillis)
+    }
 
     // —— 铸新键：没有对得上的记录时 ——
 
@@ -55,7 +72,7 @@ class RetryKeyMemoryTest {
     fun `an empty memory mints a brand new key`() {
         val minter = KeyMinter()
 
-        val decision = RetryKeyMemory().keyFor(text, minter::next)
+        val decision = RetryKeyMemory().keyFor(text, t0, minter::next)
 
         assertEquals("new-1", decision.localId)
         assertEquals(1, minter.count)
@@ -67,23 +84,26 @@ class RetryKeyMemoryTest {
         val memory = failed(text to "local-K1", other to "local-K2")
         val minter = KeyMinter()
 
-        val decision = memory.keyFor(edited, minter::next)
+        val decision = memory.keyFor(edited, t0, minter::next)
 
         // 未命中 ≠ 记忆作废：这里是「另一条消息」，不是「那两条记录都不算数了」。
         assertEquals("new-1", decision.localId)
         assertEquals(1, minter.count)
         assertSame(memory, decision.memory)
-        assertEquals(listOf(RetryKeySlot(text, "local-K1"), RetryKeySlot(other, "local-K2")), decision.memory.slots)
+        assertEquals(
+            listOf(RetryKeySlot(text, "local-K1", t0), RetryKeySlot(other, "local-K2", t0)),
+            decision.memory.slots,
+        )
     }
 
     // —— 复用：指纹一字不差 ——
 
     @Test
     fun `the same content sent again reuses the key that failed`() {
-        val remembered = RetryKeyMemory().remember(text, "local-K1")
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
         val minter = KeyMinter()
 
-        val decision = remembered.keyFor(text, minter::next)
+        val decision = remembered.keyFor(text, t0, minter::next)
 
         // 键保住了，服务端才可能用 `chat_duplicate` / `{duplicate:true}` 认出这是同一条。
         assertEquals("local-K1", decision.localId)
@@ -93,7 +113,7 @@ class RetryKeyMemoryTest {
     @Test
     fun `only a fingerprint that matches exactly reuses the key`() {
         val original = MessageFingerprint.of("你好", "content://img/1", listOf(doc("content://doc/a")))
-        val remembered = RetryKeyMemory().remember(original, "local-K1")
+        val remembered = RetryKeyMemory().remember(original, "local-K1", t0)
 
         // 三根轴各差一点点，都必须走「铸新键」这一支：正文多一个空格 / 换了图 / 少一个附件 /
         // 多一个附件。任何一条判成「同一条」，用户这次的改动就发不出去。
@@ -109,25 +129,25 @@ class RetryKeyMemoryTest {
         )
         variants.forEachIndexed { index, variant ->
             val minter = KeyMinter()
-            assertEquals("new-1", remembered.keyFor(variant, minter::next).localId)
+            assertEquals("new-1", remembered.keyFor(variant, t0, minter::next).localId)
             assertEquals(1, minter.count)
         }
 
         // 对照组：原封不动的那条仍然复用（上面每一条的差别都真的来自内容）。
-        assertEquals("local-K1", remembered.keyFor(original) { "new-x" }.localId)
+        assertEquals("local-K1", remembered.keyFor(original, t0) { "new-x" }.localId)
     }
 
     @Test
     fun `the retry that used the key consumes exactly that record`() {
-        val remembered = RetryKeyMemory().remember(text, "local-K1")
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
 
-        val afterUse = remembered.keyFor(text) { "local-K1" }.memory
+        val afterUse = remembered.keyFor(text, t0) { "local-K1" }.memory
         assertTrue(afterUse.slots.isEmpty())
 
         // 用户后来**又打了一遍**同样的话（上一条早就发出去了）：那是真的第二条消息，
         // 必须铸新键 —— 记录要是留在这儿，这句话会被服务端当重复吞掉，屏幕上什么都不出现。
         val minter = KeyMinter()
-        assertEquals("new-1", afterUse.keyFor(text, minter::next).localId)
+        assertEquals("new-1", afterUse.keyFor(text, t0, minter::next).localId)
         assertEquals(1, minter.count)
     }
 
@@ -135,12 +155,15 @@ class RetryKeyMemoryTest {
     fun `consuming the hit leaves every other slot in place`() {
         val memory = failed(text to "local-K1", other to "local-K2", edited to "local-K3")
 
-        val afterHit = memory.keyFor(other) { "new-x" }.memory
+        val afterHit = memory.keyFor(other, t0) { "new-x" }.memory
 
-        assertEquals(listOf(RetryKeySlot(text, "local-K1"), RetryKeySlot(edited, "local-K3")), afterHit.slots)
+        assertEquals(
+            listOf(RetryKeySlot(text, "local-K1", t0), RetryKeySlot(edited, "local-K3", t0)),
+            afterHit.slots,
+        )
     }
 
-    // —— 多槽：各自失败、各自复用（本次改动的核心） ——
+    // —— 多槽：各自失败、各自复用 ——
 
     @Test
     fun `two failures each keep their own key however the user retries them`() {
@@ -148,10 +171,10 @@ class RetryKeyMemoryTest {
         val minter = KeyMinter()
 
         // 用户的重试顺序不必和失败顺序一致：先重试更早失败的 `text`，同样落回**它自己**的键。
-        val afterText = memory.keyFor(text, minter::next)
+        val afterText = memory.keyFor(text, t0, minter::next)
         assertEquals("local-K1", afterText.localId)
 
-        val afterOther = afterText.memory.keyFor(other, minter::next)
+        val afterOther = afterText.memory.keyFor(other, t0, minter::next)
         assertEquals("local-K2", afterOther.localId)
         assertEquals(0, minter.count)
     }
@@ -161,10 +184,10 @@ class RetryKeyMemoryTest {
         val memory = failed(text to "local-K1", other to "local-K2")
         val minter = KeyMinter()
 
-        val afterOther = memory.keyFor(other, minter::next)
+        val afterOther = memory.keyFor(other, t0, minter::next)
         assertEquals("local-K2", afterOther.localId)
 
-        assertEquals("local-K1", afterOther.memory.keyFor(text, minter::next).localId)
+        assertEquals("local-K1", afterOther.memory.keyFor(text, t0, minter::next).localId)
         assertEquals(0, minter.count)
     }
 
@@ -172,32 +195,122 @@ class RetryKeyMemoryTest {
     fun `retrying one failed message does not wipe the other slot`() {
         val memory = failed(text to "local-K1", other to "local-K2")
 
-        val afterRetry = memory.keyFor(text) { "new-1" }.memory
+        val afterRetry = memory.keyFor(text, t0) { "new-1" }.memory
 
         // 单槽时代这一步会清空整份记忆 ⇒ 之后重试 B 只能铸新键，而 B 那次失败完全可能是
         // 「服务端其实已经收下、客户端判成失败」：那次重发就落成了第二条消息，正是本机制要消灭的重复。
-        assertEquals(listOf(RetryKeySlot(other, "local-K2")), afterRetry.slots)
-        assertEquals("local-K2", afterRetry.keyFor(other, KeyMinter()::next).localId)
+        assertEquals(listOf(RetryKeySlot(other, "local-K2", t0)), afterRetry.slots)
+        assertEquals("local-K2", afterRetry.keyFor(other, t0, KeyMinter()::next).localId)
     }
 
     @Test
     fun `remembering the same content again updates its key instead of adding a second slot`() {
         // 同一条（指纹相同）又失败一次：键换成新的，槽还是那一个（并列两条只会命中更早那条，
         // 用户的重试反而用不上刚铸的键）。
-        val memory = failed(text to "local-K1", other to "local-K2").remember(text, "local-K1b")
+        val memory = failed(text to "local-K1", other to "local-K2").remember(text, "local-K1b", t0)
 
-        assertEquals(listOf(RetryKeySlot(other, "local-K2"), RetryKeySlot(text, "local-K1b")), memory.slots)
-        assertEquals("local-K1b", memory.keyFor(text, KeyMinter()::next).localId)
+        assertEquals(
+            listOf(RetryKeySlot(other, "local-K2", t0), RetryKeySlot(text, "local-K1b", t0)),
+            memory.slots,
+        )
+        assertEquals("local-K1b", memory.keyFor(text, t0, KeyMinter()::next).localId)
+    }
+
+    // —— 时间上界：过期槽视同不存在（本次改动的核心） ——
+
+    @Test
+    fun `a slot older than the TTL is not reused and gets dropped`() {
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
+        val minter = KeyMinter()
+
+        val decision = remembered.keyFor(text, pastTheBoundary, minter::next)
+
+        // 用户几小时前失败过一句「你好」，今天**新**打一遍：在他心里那是另一条消息。复用旧键会让
+        // 服务端回 `duplicate` 把这条新消息吞掉 —— 屏幕上什么都不出现，看着像「按了没反应」。
+        assertEquals("new-1", decision.localId)
+        assertEquals(1, minter.count)
+        // 淘汰是顺带的：作废的那条不留下占额度（下一次 [RetryKeyMemory.MAX_SLOTS] 满了时它不该在场）。
+        assertTrue(decision.memory.slots.isEmpty())
+    }
+
+    @Test
+    fun `a slot exactly at the TTL boundary still counts as fresh`() {
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
+        val minter = KeyMinter()
+
+        // 边界口径钉在这里：判据是 `now - atMillis > TTL`（**严格大于**），所以正好等于 TTL 的这一
+        // 毫秒**仍然**命中，过期要再晚一毫秒（上一条）。选这一边是因为常量自身就是一条可直接断言的
+        // 「还活着」的边界值，不必为它发明魔法数；真实时钟也几乎不可能精确落在这一毫秒上。
+        val decision = remembered.keyFor(text, atTheBoundary, minter::next)
+
+        assertEquals("local-K1", decision.localId)
+        assertEquals(0, minter.count)
+    }
+
+    @Test
+    fun `a lookup that expires nothing leaves the memory instance untouched`() {
+        val memory = failed(text to "local-K1")
+
+        // 未过期的那条不该因为查了一次就被重写：淘汰只在真的有时过期的改写这份记忆。
+        assertSame(memory, memory.keyFor(edited, atTheBoundary, KeyMinter()::next).memory)
+        assertSame(memory, memory.forget("local-other"))
+    }
+
+    @Test
+    fun `an expired slot does not cost a fresh one its key`() {
+        // A 记在 [t0]（马上就过期），B 记在很久以后（新鲜）—— 两条同处一份记忆。
+        val memory = failed(text to "local-K1").remember(other, "local-K2", pastTheBoundary)
+
+        // 命中新鲜的那条：A 被顺手淘汰，B 照常给出自己的键、并被消费掉。
+        val hitB = memory.keyFor(other, pastTheBoundary, KeyMinter()::next)
+        assertEquals("local-K2", hitB.localId)
+        assertTrue(hitB.memory.slots.isEmpty())
+
+        // 同一时刻问那条过期的 A：结果是**新键**（与「从来没记过」一样），而 B 的槽原样留着。
+        val minter = KeyMinter()
+        val missA = memory.keyFor(text, pastTheBoundary, minter::next)
+        assertEquals("new-1", missA.localId)
+        assertEquals(1, minter.count)
+        assertEquals(listOf(RetryKeySlot(other, "local-K2", pastTheBoundary)), missA.memory.slots)
+    }
+
+    @Test
+    fun `remembering a new failure drops the ones that have expired`() {
+        val memory = RetryKeyMemory().remember(text, "local-K1", t0)
+
+        val later = memory.remember(other, "local-K2", pastTheBoundary)
+
+        // 写入口也先按时间清：过期槽一个都不留，新写的那条马上就认得出自己的键。
+        assertEquals(listOf(RetryKeySlot(other, "local-K2", pastTheBoundary)), later.slots)
+        assertEquals("local-K2", later.keyFor(other, pastTheBoundary, KeyMinter()::next).localId)
+    }
+
+    @Test
+    fun `remembering the same content again refreshes its timestamp`() {
+        val firstFailure = RetryKeyMemory().remember(text, "local-K1", t0)
+
+        // 用户 7.5 分钟后重试、又失败一次：同一条消息（指纹相同）**键与时刻一起**更新。
+        val secondFailureAt = t0 + RetryKeyMemory.SLOT_TTL_MILLIS * 3 / 4
+        val refreshed = firstFailure.remember(text, "local-K1b", secondFailureAt)
+
+        // 只有一条槽：并列两条只会让 `keyFor` 命中最旧那条，而它还会**先**过期。
+        assertEquals(listOf(RetryKeySlot(text, "local-K1b", secondFailureAt)), refreshed.slots)
+
+        // 关键一刻：此时距**第一次**失败早已超过 TTL，距**更新**才过了 TTL/4。刚记下的失败必须还能
+        // 复用 —— 若时间戳不刷新，用户紧接着的重试会铸新键，「服务端其实已收下」的那条就落成第二条。
+        val minter = KeyMinter()
+        assertEquals("local-K1b", refreshed.keyFor(text, pastTheBoundary, minter::next).localId)
+        assertEquals(0, minter.count)
     }
 
     // —— 编辑：重铸但不迁怒别的槽 ——
 
     @Test
     fun `an edit mints a new key and keeps the failed record`() {
-        val remembered = RetryKeyMemory().remember(text, "local-K1")
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
         val minter = KeyMinter()
 
-        val decision = remembered.keyFor(edited, minter::next)
+        val decision = remembered.keyFor(edited, t0, minter::next)
 
         // 改过字就是**另一条**消息：复用旧键会让服务端判重，用户这次的编辑一个字都发不出去。
         assertEquals("new-1", decision.localId)
@@ -208,14 +321,14 @@ class RetryKeyMemoryTest {
 
     @Test
     fun `an edit does not cost the original text its key`() {
-        val remembered = RetryKeyMemory().remember(text, "local-K1")
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
 
         // 「改了再发」这一步不清槽 ⇒ 之后发回原来那句话仍然拿得回旧键。这是「未命中不清」的代价：
         // 单槽时代的测试在这里断言的是「铸新键」，多槽下那条断言**不再成立**，也不是我们想要的。
-        val afterEdit = remembered.keyFor(edited) { "new-1" }.memory
+        val afterEdit = remembered.keyFor(edited, t0) { "new-1" }.memory
 
         val minter = KeyMinter()
-        assertEquals("local-K1", afterEdit.keyFor(text, minter::next).localId)
+        assertEquals("local-K1", afterEdit.keyFor(text, t0, minter::next).localId)
         assertEquals(0, minter.count)
     }
 
@@ -229,22 +342,42 @@ class RetryKeyMemoryTest {
         }
 
         val memory = records.fold(RetryKeyMemory()) { acc, (fingerprint, localId) ->
-            acc.remember(fingerprint, localId)
+            acc.remember(fingerprint, localId, t0)
         }
 
         assertEquals(RetryKeyMemory.MAX_SLOTS, memory.slots.size)
         assertEquals(
-            records.takeLast(RetryKeyMemory.MAX_SLOTS).map { RetryKeySlot(it.first, it.second) },
+            records.takeLast(RetryKeyMemory.MAX_SLOTS).map { RetryKeySlot(it.first, it.second, t0) },
             memory.slots,
         )
 
         // 刚写进去的那条一定在（淘汰只可能从头开始），还认得出自己的键。
         val minter = KeyMinter()
-        assertEquals("local-K${count - 1}", memory.keyFor(records.last().first, minter::next).localId)
+        assertEquals("local-K${count - 1}", memory.keyFor(records.last().first, t0, minter::next).localId)
         assertEquals(0, minter.count)
 
         // 被挤出去的那条就只剩「铸新键」了：它的键确实已经不在记忆里。
-        assertEquals("new-1", memory.keyFor(records.first().first, minter::next).localId)
+        assertEquals("new-1", memory.keyFor(records.first().first, t0, minter::next).localId)
+    }
+
+    @Test
+    fun `the TTL is applied before the FIFO cap counts`() {
+        // 8 条全记在 [t0]，正好顶到条数上限（上限在 TTL 之内依然生效）。
+        val records = List(RetryKeyMemory.MAX_SLOTS) { index ->
+            MessageFingerprint.of("第 $index 条", null, emptyList()) to "local-K$index"
+        }
+        val full = records.fold(RetryKeyMemory()) { acc, (fingerprint, localId) ->
+            acc.remember(fingerprint, localId, t0)
+        }
+        assertEquals(RetryKeyMemory.MAX_SLOTS, full.slots.size)
+
+        // 过期那一刻再写一条新的。
+        val afterExpiry = full.remember(edited, "local-Knew", pastTheBoundary)
+
+        // 顺序是「先按时间清、写入时最后才看条数」：8 个过期槽一个都不留，新写的这条**不**会被它们
+        // 挤出上限（反过来先砍条数的话，这里会留下 7 个死条目 + 新的那条，额度白占）。
+        assertEquals(listOf(RetryKeySlot(edited, "local-Knew", pastTheBoundary)), afterExpiry.slots)
+        assertEquals("local-Knew", afterExpiry.keyFor(edited, pastTheBoundary, KeyMinter()::next).localId)
     }
 
     // —— 清：只在无歧义时清得动 ——
@@ -253,7 +386,7 @@ class RetryKeyMemoryTest {
     fun `forget clears exactly the message that settled`() {
         val memory = failed(text to "local-K1", other to "local-K2")
 
-        assertEquals(listOf(RetryKeySlot(other, "local-K2")), memory.forget("local-K1").slots)
+        assertEquals(listOf(RetryKeySlot(other, "local-K2", t0)), memory.forget("local-K1").slots)
     }
 
     @Test
@@ -272,8 +405,8 @@ class RetryKeyMemoryTest {
     fun `a retried message the server already has collapses into the single persisted bubble`() {
         // 全链路：失败时记住键 ⇒ 用户按发送复用它 ⇒ 服务端按同一个键判重 ⇒ 客户端只摘待发气泡，
         // 由**原来那条**落库消息顶上（不再冒出第二个气泡，也不再另造一套对齐逻辑）。
-        val remembered = RetryKeyMemory().remember(text, "local-K1")
-        val retryKey = remembered.keyFor(text) { "new-1" }.localId
+        val remembered = RetryKeyMemory().remember(text, "local-K1", t0)
+        val retryKey = remembered.keyFor(text, t0) { "new-1" }.localId
         assertEquals("local-K1", retryKey)
 
         val persisted = HistoryMessageDto(