memleaf 0.2.82__tar.gz → 0.2.84__tar.gz

{memleaf-0.2.82 → memleaf-0.2.84}/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.84 — 2026-09-30
+
+### Task lifecycle, Hermes source times and read-linked comparison
+
+- Expose revision-bound MCP `update_memory` for completion, cancellation and
+  reopening; retain the memory body, other fields and version history. Both MCP
+  permanent-forgetting tools now require strict `confirm_delete=true`.
+- Verify Hermes' native file-mutation footer as an exact display transformation
+  instead of losing both message times. Verify legacy correction rows against
+  their native scaffold and full merge format; capture each source event with
+  its own timestamp. Unknown inputs remain unknown.
+- Recognize a repeated source delivery before consuming another same-text turn;
+  copy messages at callback invocation and retain the queued retrieval identity.
+- Freeze successful current-turn read IDs in assistant capture metadata and
+  immutable receipts. Prioritize those targets for automatic extraction; reject
+  mismatched source/session/turn context and block missing or over-budget targets.
+  Recover captured context after Inbox/receipt interruption even if the gate expires.
+- Require structured deadline maintenance before NO_CHANGE when current evidence
+  verifies an existing textual deadline whose date is absent or unresolved.
+  Advance semantic protocol to v11 without changing legacy snapshot field contracts.
+- No production memory migration or automatic retry of historical runs is performed.
+
+## 0.2.83 — 2026-09-30
+
+### Reviewed extraction fields and existing-item maintenance
+
+- Compare established identifiers and other facts against existing unknowns
+  before NO_CHANGE, including shared project facts when creating an independent
+  task. Project/task identity remains model-owned; Core does not merge titles.
+- Add the `field-reviewed-v1` request contract: CREATE/UPDATE explicitly decide
+  whether to select a structural deadline or leave it absent/unchanged. CREATE
+  explicitly records unknown executors as null; changed non-null responsibility
+  fields require a verifiable source quote.
+- Preserve selected deadline and responsibility provenance. Unknown CREATE
+  responsibility and unchanged inherited responsibility do not advance its basis.
+  Project existing `actionable` metadata and clarify new/context boundaries.
+- Advance semantic protocol to v10. Legacy snapshot digests remain readable;
+  repair retains its original field contract and replan uses the current one.
+  Existing runtime protocol gates still apply to historical partial runs.
+- Validation: 86 focused checks, six real-model synthetic scenarios and six
+  isolated capture/commit/repeated-replay scenarios passed. The 182-check local
+  comparison has nine pre-existing date assertions failing on both versions,
+  with no new failures. No formal Vault or historical run was changed.
+
 ## 0.2.82 — 2026-09-30
 
 ### Hermes installation tool discovery

{memleaf-0.2.82/src/memleaf.egg-info → memleaf-0.2.84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.82
+Version: 0.2.84
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,10 +23,10 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.82。**
+> **版本：0.2.84。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
-> 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
-> Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。
+> 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。Core 不按标题强行合并。
+> 新请求使用 `field-reviewed-v1`：CREATE/UPDATE 显式判断结构化期限；未知执行人填 `null`，新增或变更非空负责人必须引用来源原文。Core 校验字段和来源，模型判断业务含义；非法行进入现有 partial 处理。来源时间用于解析相对日期，不补造事实日期。
 > 待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -283,11 +283,14 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `process_status` | 只读查询异步处理 job 状态 |
 | `recover_failed_run` | 预览并显式恢复终态传输失败，保留原请求预算 |
 | `remember` | 用户明确要求时创建或更新记忆 |
-| `forget_memory` | 按精确 ID 删除一条记忆 |
-| `forget_about` | 忘记明确主题；有歧义时只返回候选 |
+| `update_memory` | 携带当前 revision 办结、取消或重新激活任务，保留正文与历史 |
+| `forget_memory` | 用户明确要求遗忘时，携带 `confirm_delete=true` 按精确 ID 永久删除 |
+| `forget_about` | 携带 `confirm_delete=true` 遗忘明确主题；有歧义时只返回候选 |
 | `rebuild_index` | 重建可重建的本地派生索引 |
 | `stats` | 返回 Vault 计数和诊断统计 |
 
+任务办结与永久遗忘的接口和兼容性见 [生命周期工具](docs/memory-lifecycle-tools.md)；来源时间及本轮比较目标的捕获边界见 [Hermes 来源与比较上下文](docs/hermes-source-comparison-context.md)。
+
 `search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一条检索链的 `retrieval_id` 完成 `search → read`。Hermes/Codex Hook 可直接提供该 token；只有 MCP 的客户端可在第一条 `search` / `list_todos` 省略 token，并使用返回值继续分页和读取。带 cursor 的后续页以及所有 `read` 都不能省略 `retrieval_id`。工具错误、Scope 冲突或读取失败都应如实处理。
 
 ## Python API

{memleaf-0.2.82 → memleaf-0.2.84}/README.en.md

@@ -4,10 +4,10 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.82.**
+> **Version: 0.2.84.**
 > Automatic extraction and review share one future-value standard: the model weighs likely reuse, information gain, direct usability when read again, and the cost of forgetting. It keeps only the smallest core that can materially help future understanding, decisions, or actions; information without clear value is not extracted, and no business-specific exclusion rule is hard-coded.
-> A single Chinese semantic contract is sent for extraction, topic selection, candidate repair, and `semantic_maintenance`; the older English B3 prompt has been deleted and B3 remains only as a compatibility read format. One topic is written once.
-> Core no longer discards a whole candidate over ownership, dates, task basis or cross-project wording. A missing owner normalizes to the single project named by that candidate's own evidence, otherwise `global`. A deadline is accepted only when it appears in the candidate's own evidence and can be anchored to ISO (`明天`, `周五`, `月底` all resolve); when it cannot, only the date field is dropped and the memory is still written. An unauthorized ownership change keeps the target's existing scope.
+> Extraction compares existing identifiers, objectives, progress, responsibility and deadlines first. Filling an unknown also maintains the original item; a separate task does not replace updating shared project facts. Core does not merge matching titles.
+> New requests use `field-reviewed-v1`: CREATE/UPDATE explicitly decide structural deadlines; unknown executors use `null`, and new or changed non-null responsibility requires a source quote. Core validates fields and provenance while the model judges business meaning; invalid rows use existing partial handling. Source time resolves relative dates without inventing factual dates.
 > A todo's `due_date` means only the explicit deadline of the todo action; dates describing its subject or desired outcome are not deadlines. Project ownership remains the model's semantic judgement and needs no literal name match. The review stage now keeps the update target chosen by the first pass, so a state change is no longer downgraded into a new memory. Markdown remains the sole source of truth.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
@@ -264,11 +264,14 @@ The server exposes the following tools:
 | `process_status` | Read the status of a background processing job |
 | `recover_failed_run` | Preview and explicitly recover terminal transport failures within the original request budget |
 | `remember` | Create or update memory after an explicit request |
-| `forget_memory` | Delete one memory by exact ID |
-| `forget_about` | Forget an unambiguous topic; return candidates when ambiguous |
+| `update_memory` | Complete, cancel or reopen a task using its current revision; retain body and history |
+| `forget_memory` | Permanently delete an exact ID after explicit user forgetting, with `confirm_delete=true` |
+| `forget_about` | Forget an unambiguous topic with `confirm_delete=true`; return candidates when ambiguous |
 | `rebuild_index` | Rebuild local derived indexes |
 | `stats` | Return Vault counts and diagnostic statistics |
 
+See [Lifecycle tools](docs/memory-lifecycle-tools.md) and [Hermes source and comparison context](docs/hermes-source-comparison-context.md) for operation and capture boundaries.
+
 Search results are clues; a title alone is not a business fact. Managed retrieval must use the same `retrieval_id` for `search → read`. Tool errors, Scope conflicts, retrieval-turn violations, and read page/version errors must be handled as such.
 
 ## Python API

{memleaf-0.2.82 → memleaf-0.2.84}/README.md

@@ -4,10 +4,10 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.82。**
+> **版本：0.2.84。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
-> 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
-> Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。
+> 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。Core 不按标题强行合并。
+> 新请求使用 `field-reviewed-v1`：CREATE/UPDATE 显式判断结构化期限；未知执行人填 `null`，新增或变更非空负责人必须引用来源原文。Core 校验字段和来源，模型判断业务含义；非法行进入现有 partial 处理。来源时间用于解析相对日期，不补造事实日期。
 > 待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -264,11 +264,14 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `process_status` | 只读查询异步处理 job 状态 |
 | `recover_failed_run` | 预览并显式恢复终态传输失败，保留原请求预算 |
 | `remember` | 用户明确要求时创建或更新记忆 |
-| `forget_memory` | 按精确 ID 删除一条记忆 |
-| `forget_about` | 忘记明确主题；有歧义时只返回候选 |
+| `update_memory` | 携带当前 revision 办结、取消或重新激活任务，保留正文与历史 |
+| `forget_memory` | 用户明确要求遗忘时，携带 `confirm_delete=true` 按精确 ID 永久删除 |
+| `forget_about` | 携带 `confirm_delete=true` 遗忘明确主题；有歧义时只返回候选 |
 | `rebuild_index` | 重建可重建的本地派生索引 |
 | `stats` | 返回 Vault 计数和诊断统计 |
 
+任务办结与永久遗忘的接口和兼容性见 [生命周期工具](docs/memory-lifecycle-tools.md)；来源时间及本轮比较目标的捕获边界见 [Hermes 来源与比较上下文](docs/hermes-source-comparison-context.md)。
+
 `search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一条检索链的 `retrieval_id` 完成 `search → read`。Hermes/Codex Hook 可直接提供该 token；只有 MCP 的客户端可在第一条 `search` / `list_todos` 省略 token，并使用返回值继续分页和读取。带 cursor 的后续页以及所有 `read` 都不能省略 `retrieval_id`。工具错误、Scope 冲突或读取失败都应如实处理。
 
 ## Python API

memleaf-0.2.84/docs/hermes-source-comparison-context.md

@@ -0,0 +1,60 @@
+# Hermes source and comparison context
+
+## Message times
+
+`source_time` comes from the corresponding message's `source_time` or
+`timestamp`. Missing or invalid values stay unknown. Capturing or processing
+an event does not create a source time.
+
+The legacy callback checks the final assistant and the nearest user. It has no
+32-message lookback limit. It does not borrow a matching user from an older turn.
+
+Some Hermes versions persist a reply before adding their file-mutation verifier
+footer. The Provider accepts that display transformation only when the installed
+Hermes formatter reconstructs the entire footer from uniquely associated,
+current-turn file-tool receipts and the full resulting reply matches. Arbitrary
+prefixes, suffixes, unsupported formatters and ambiguous receipts remain unknown.
+Tool receipts supply no times or memory facts. The displayed reply remains the
+captured assistant content.
+
+For legacy corrections, the Provider verifies the real user rows, native replay
+scaffold and the exact full merged callback string. It never splits arbitrary
+user text by a separator. A bounded chain must have a queued original admission;
+then each source row is captured separately with its own time. It does not assign
+the final correction's time to the combined user text. A repeated source delivery
+is recognized before consuming another same-text admission. Host-v1 admission
+snapshots remain the preferred interface for compaction and transformations that
+legacy callbacks cannot verify. The list is copied at callback invocation; this
+cannot recover a host snapshot already lost before the callback arrives.
+
+## Successful reads as comparison targets
+
+Hermes uses the retrieval identity frozen at `on_turn_start` for final capture.
+The assistant capture includes `retrieval_id` and `retrieval_turn_id`; the latter
+must equal its `turn_id`. Core checks that the existing gate belongs to exactly
+the declared source, session and turn. It never resolves a session's latest gate
+on behalf of an older callback. Live search and read still reject stale tokens.
+
+Core freezes only successfully read memory IDs into `comparison_context` on the
+assistant event, including the immutable capture receipt and payload digest.
+It accepts no caller-supplied list of IDs through this interface. The capsule is
+comparison metadata, not factual evidence, and its token is not projected into
+the model request. Automatic preparation gives these required targets priority
+alongside explicit-write receipts before filling the bounded candidate budget.
+A missing target or insufficient budget blocks preparation instead of silently
+replacing or dropping the required target. No model call is added to capture.
+
+A delayed callback can use its own unexpired gate even after a later turn starts.
+Once the capsule is captured, gate expiry cannot erase it or break a duplicate
+capture. If Inbox was saved but receipt persistence failed, retries first recover
+the capsule from Inbox before consulting a live gate. An uncaptured, expired or
+mismatched gate cannot supply comparison context.
+
+The extraction prompt also requires structured deadline maintenance before
+NO_CHANGE when current evidence makes an existing unstructured deadline
+verifiable. Unchanged wording does not mean a missing due_date is complete.
+This rule advances the semantic protocol to v11.
+
+This supplies the model with the old targets. It does not force semantic UPDATE,
+merge similar titles, or automatically alter historical memories. Recovery of
+existing production runs and deleted records is a separate operation.

{memleaf-0.2.82 → memleaf-0.2.84}/docs/incremental-planner-preview.md

@@ -59,6 +59,36 @@ CREATE proposals have no permanent ID. UPDATE proposals carry the original
 
 The version is `incremental-items-v1`; only `{"items": [...]}` is accepted.
 
+New prepared requests also carry `extraction_contract=field-reviewed-v1`:
+
+- Every CREATE/UPDATE includes row-level `deadline_decision`. Use `selected`
+  with `memory.deadline` for CREATE or `patch.deadline` for UPDATE; use `none`
+  for CREATE without an established deadline, or `unchanged` for UPDATE without
+  a deadline change. A deadline mentioned only in prose is insufficient.
+- CREATE explicitly supplies `memory.assignee`, using null when the executor
+  is unknown. New or changed non-null `assignee`/`waiting_on` requires row-level
+  `responsibility_basis`, keyed by that field, with `{ref, text}` citing an exact
+  source quote in the row's evidence. An unchanged inherited owner needs no new
+  quote. Field provenance uses the selected source rather than the generic row
+  observation; merely inheriting responsibility does not advance its basis.
+- The model compares established identifiers and other new facts against old
+  unknowns before choosing NO_CHANGE, including project facts when it also
+  creates an independent task. Existing `actionable` metadata is projected.
+
+Core checks explicit choices, shape and source provenance; it does not classify
+the meaning of a quote or automatically merge similar titles. Model semantic
+errors remain possible. Invalid rows become unresolved through the existing
+partial handling, without an additional model dispatch.
+
+Frozen snapshots without this marker retain their original contract and digest.
+Partial repair retains the original contract; replanning uses the current one.
+The semantic request version advances so a pre-commit request prepared under an
+older prompt cannot silently continue under this new prompt.
+These snapshot rules preserve capsule reading and reconstruction; the existing
+runtime protocol gate still applies. An older partial run may return
+`partial_protocol_upgrade_required` before repair/replan; this change does not
+authorize continuing that historical run across protocol versions.
+
 | action | Required fields besides action/evidence | Behavior |
 |---|---|---|
 | CREATE | memory.type/scope/title/body; todo also status | Independent new assertion; Core defaults validity=valid |

memleaf-0.2.84/docs/memory-lifecycle-tools.md

@@ -0,0 +1,26 @@
+# 任务办结与永久遗忘
+
+MCP `update_memory` 用于完成、取消或重新打开现有事项。它调用 Core 的 revision-bound 更新接口，保留原正文、未修改字段及历史版本，不调用模型。任务办结不等于删除记忆。
+
+先通过 `search` / `list_todos` 和 `read` 确认目标。使用 `read` 返回的 `revision`，而不是分页用的 `version`：
+
+```json
+{
+  "memory_id": "mem-example",
+  "expected_revision": "<read 返回的 revision>",
+  "patch": {"status": "completed"}
+}
+```
+
+- 已完成或关闭的事项使用 `completed`，放弃的事项使用 `cancelled`。
+- 本 MCP 接口仅接受 `patch.status`，不修改正文、类型或范围。
+- 重新打开事项使用 `patch.status=active` 和 `reopen=true`，应有用户明确重新打开的要求。
+- 只有明确知道事项的完成事件时间时才传 `source_time`（带时区的 ISO 时间）；完成时会保存为 `completed_at`。未知时省略，不使用当前执行时间补造完成时间。
+- 相同请求可以安全重试，不重复创建历史。旧 revision 的不同修改会被拒绝，应重新读取目标。
+- 混合了项目事实和待办的记忆，办结只改变状态，仍保留项目事实。
+
+`forget_memory` 与 `forget_about` 永久删除选中的记忆及其历史，没有“删除后收档”的历史副本。两个 MCP 工具均要求 `confirm_delete=true`，缺失或不是布尔值 `true` 时服务器拒绝执行。
+
+这个参数只能表示调用方确认用户明确要求永久遗忘。完成、关闭、取消或归档任务不能作为设置它的理由。布尔参数本身不是用户自然语言授权的证明，也不能保证模型永远正确选择工具。需要撤销任务完成状态时，应通过 `update_memory` 重新打开；已永久删除的内容不能用此接口恢复。
+
+这是 MCP 删除接口的兼容性变更：旧客户端应只在已有明确永久遗忘要求时补传 `confirm_delete=true`。Python Core 的 `forget_memory` / `forget_about` 原有删除语义及参数保持不变。

{memleaf-0.2.82 → memleaf-0.2.84}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memleaf"
-version = "0.2.82"
+version = "0.2.84"
 description = "A local-first Markdown memory core for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

{memleaf-0.2.82 → memleaf-0.2.84}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.82"
+__version__ = "0.2.84"
 
 from .config import DEFAULT_CONFIG, default_config, load_config, save_config
 from .frontmatter import FrontmatterError, dump_frontmatter, dump_yaml, load_yaml, parse_frontmatter

{memleaf-0.2.82 → memleaf-0.2.84}/src/memleaf/capture.py

@@ -199,6 +199,7 @@ def _append_event(
     final: bool | None,
     tool_evidence: list[dict[str, str]] | None = None,
     explicit_input: dict[str, Any] | None = None,
+    comparison_context: dict[str, Any] | None = None,
 ) -> str:
     if not existing:
         existing = _new_session_text(source, session_id, captured_at)
@@ -232,6 +233,8 @@ def _append_event(
         metadata["final"] = final
     if explicit_input is not None:
         metadata["explicit_input"] = explicit_input
+    if comparison_context is not None:
+        metadata["comparison_context"] = comparison_context
     if tool_evidence:
         metadata["tool_evidence"] = [dict(item) for item in tool_evidence]
     metadata_line = json.dumps(metadata, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
@@ -359,6 +362,8 @@ def _payload_digest(metadata: Mapping[str, Any], content: str) -> str:
     if metadata.get("explicit_input") is not None:
         from .explicit_text_source import validate_origin
         value["explicit_input"] = validate_origin(metadata["explicit_input"])
+    if metadata.get("comparison_context") is not None:
+        value["comparison_context"] = metadata["comparison_context"]
     value["content"] = content.rstrip("\n")
     return hashlib.sha256(json.dumps(value, ensure_ascii=False, sort_keys=True,
                                     separators=(",", ":")).encode("utf-8")).hexdigest()
@@ -414,7 +419,7 @@ def recover_capture_receipts_unlocked(vault: Vault, processed: dict, path: Path)
             turn_key_value=metadata["turn_key"], turn_index=metadata["turn_index"],
             message_id=metadata["message_id"], message_revision=metadata["message_revision"],
         )
-        entry = {field: metadata[field] for field in (*_IMMUTABLE_EVENT_FIELDS, "turn_id", "turn_index", "captured_at", "explicit_input")
+        entry = {field: metadata[field] for field in (*_IMMUTABLE_EVENT_FIELDS, "turn_id", "turn_index", "captured_at", "explicit_input", "comparison_context")
                  if field in metadata}
         entry.update(event_key=key, payload_digest=digest)
         events[key] = entry
@@ -447,6 +452,8 @@ def capture_event(
     previous_message_id: Optional[str] = None,
     final: Optional[bool] = None,
     _explicit_input: dict[str, Any] | None = None,
+    retrieval_id: Optional[str] = None,
+    retrieval_turn_id: Optional[str] = None,
 ) -> CaptureResult:
     """Capture one visible event; all persisted text is redacted first."""
 
@@ -478,6 +485,9 @@ def capture_event(
         # Opting into source envelopes does not implicitly certify completion.
         # Old callers with no source metadata retain their legacy boundary.
         final = False
+    if (retrieval_id is None) != (retrieval_turn_id is None) or (
+            retrieval_id is not None and (role != "assistant" or retrieval_turn_id != turn_id)):
+        raise ValueError("invalid_comparison_binding")
     resolved_event_id, resolved_message_id, resolved_event_key = _event_identity(
         source, session_id, turn_id, role, event_id, message_id, message_revision
     )
@@ -488,6 +498,31 @@ def capture_event(
     if not visible or role not in ("user", "assistant"):
         return CaptureResult(resolved_event_id, stored=False, duplicate=False, content=safe_content)
 
+    comparison_context = None
+    if retrieval_id is not None:
+        # Never hold the vault lock while acquiring the retrieval lock: gated
+        # reads acquire them in the opposite order. Durable retries reuse their
+        # immutable receipt even after the short-lived gate has expired.
+        with vault.lock():
+            recovered = _read_processed(vault.processed_state_path)
+            from .recording_policy import recording_allowed
+            comparison_permitted = record and recording_allowed(recovered, source, session_id, resolved_turn_key)
+            if comparison_permitted:
+                path = vault.session_path(source, session_id)
+                if path.is_symlink():
+                    raise ValueError("unsafe inbox session path")
+                if recover_capture_receipts_unlocked(vault, recovered, path):
+                    atomic_write_json(vault.processed_state_path, recovered)
+            receipt = recovered.get("events", {}).get(resolved_event_key, {})
+            saved = receipt.get("comparison_context") if isinstance(receipt, Mapping) else None
+        if (isinstance(saved, dict) and saved.get("retrieval_id") == retrieval_id
+                and saved.get("turn_id") == retrieval_turn_id):
+            comparison_context = saved
+        elif comparison_permitted:
+            from .retrieval_gate import snapshot_read_context
+            comparison_context = snapshot_read_context(vault, retrieval_id,
+                source=source, session_id=session_id, turn_id=retrieval_turn_id)
+
     with vault.lock():
         processed = _read_processed(vault.processed_state_path)
         if _explicit_input is not None:
@@ -526,6 +561,8 @@ def capture_event(
             "previous_message_revision": previous_message_revision, "source_sequence": source_sequence,
             "previous_message_id": previous_message_id, "source_time": source_time, "final": final,
         }
+        if retrieval_id is not None:
+            incoming["comparison_context"] = comparison_context
         if _explicit_input is not None:
             incoming["explicit_input"] = _explicit_input
         digest = _payload_digest(incoming, safe_content)
@@ -584,6 +621,7 @@ def capture_event(
             final=final,
             tool_evidence=safe_tool_evidence,
             explicit_input=_explicit_input,
+            comparison_context=comparison_context,
         )
         atomic_write_text(path, updated)