memleaf 0.2.65__tar.gz → 0.2.67__tar.gz

{memleaf-0.2.65 → memleaf-0.2.67}/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 All notable changes to memleaf are documented here.
 
+## Unreleased
+
+## 0.2.67 — 2026-09-20
+
+### Incremental-only processing and release integrity
+
+- Remove the executable legacy processing/remember engine. New Vaults use the
+  incremental runner for automatic processing, explicit remember, MCP/CLI and
+  detached jobs; retained legacy settings/jobs remain inspectable but fail closed.
+- Fix the v0.2.66 Hermes Provider manifest drift by aligning Core and Provider at
+  0.2.67 and rejecting an internally inconsistent package before host/Vault changes.
+- Gate source and wheel/sdist verification on one version identity across package
+  metadata, Core `__version__`, Hermes `plugin.yaml` and sdist project metadata.
+
+
+## 0.2.66 — 2026-09-20
+
+### Reconcile divergent local candidates
+
+- Integrate the 1147-test closeout and 1128-test update candidates without losing
+  either test inventory, control-loss guards, binding, shared Writer or Forget.
+- Use one explicit-update writer with strict scope/restore flags, caller source
+  time, canonical deadline forms, retained stale evidence and settlement recheck.
+- Preserve exact recovery for both earlier v1 layouts; reject conflicting copies.
+  Expose pending counts and protect only proven retention dependencies when safe.
+- Resolve provisional API/test disagreements explicitly; no release, default
+  route, production Vault or model-request-budget changes.
+
+
+### Development closeout contracts
+
+- Add a bounded, exact Python `update_memory` with expected revision, field/scope
+  whitelist, explicit reopen/restore/type correction and forward recovery.
+- Reuse strict target scans for shared writes; preserve newer edits and read
+  counters, protect pending journals from retention, and expose their freshness.
+- Make logical-ID Forget/cancellation case-insensitive without treating a lone
+  fuzzy candidate as confirmation or damaged files as absent.
+- Refuse lost durable authority as a fresh budget; bind genuinely new local
+  Vaults without guessing the owner of legacy data. Keep supported old capsules.
+- Use bounded planner snapshots and explicit provenance status after direct
+  edits. No additional model phase, default-route switch, release or production
+  migration; external semantic and native-host final tests remain separate.
+
+
+- Validate revision lookups and explicit retractions against bounded current-ID
+  scans; reject duplicate/unreadable ownership instead of silently skipping it.
+  Recheck before history/head writes, preserve recovery journals for unreadable
+  targets, keep read accounting on retry, and qualify interrupted-write results
+  using the full protected revision. Existing v1 recovery and raw APIs remain.
+
+
+- Make `create_memory` create-only: reject existing frontmatter identities across
+  current/history files, renamed or case-variant IDs, occupied destinations and
+  unverifiable scans instead of silently replacing records. Keep trusted raw
+  `write_memory`/`save_memory`/`add_memory` overwrite compatibility, with an
+  explicit `overwrite=False` create-only option. No model or default pipeline
+  changes; general revision-checked raw updates are not introduced.
+
+- Verify copied Hermes Provider behavior resources through the existing MCP handshake and explicit installer probe; reject mismatched/unverified bridge mutations while retaining local reads. Detect in-place copy changes without refreshing a live host, validate both copy paths, and preserve safe compatibility errors. No model calls, prompt/default/version changes or automatic activation.
+
+- Restrict explicit memory compaction to independent body-only proposals. Preserve the complete original identity, state, deadlines, responsibility, provenance and custom fields; remove multi-ID merging and unrelated pre-compaction retention. Bound model inputs and keep existing rollback journals compatible.
+
+- Compare native-file ctime stability within path and descriptor observations separately: Windows CPython 3.12 can report creation time and metadata-change time through different APIs. Preserve cross-API identity/size/mtime checks, whole-content guards, and per-file bounded reads. Repair the LF-to-CRLF test fixture without skipping native platforms or weakening change detection.
+
+- Size inspection reads from each opened regular file, not the entire remaining Vault budget. Keep full-byte snapshot comparisons and reject detected growth, truncation or in-read metadata changes; avoid a roughly 256 MiB temporary allocation for tiny files during migration/audit/backup checks. No model calls, schema/default changes or release.
+
+- Gate future releases on native installed-artifact contract checks: build once, bind wheel/sdist and test inventory, then verify independent installations on Ubuntu/Python 3.11-3.13 and Windows/macOS Python 3.12. Include packaged Provider resources, real stdio/lock/restart checks and explicit failure on skipped or source-shadowed tests. This is deterministic validation, not live-model or installed-Hermes acceptance; defaults, prompt and version stay unchanged.
+
+- Avoid reparsing unchanged validated Markdown during public-query rechecks. Re-enumerate and re-read current bytes before reusing immutable request-local fingerprints; retain malformed/duplicate isolation and all existing change/bound checks. Add an isolated synthetic query benchmark without model calls, persistent cache or default changes.
+
+- Add a plan-first, explicitly budgeted isolated multi-turn acceptance utility with twelve public synthetic regression trajectories. Keep expected assertions out of model inputs, preserve private evidence traces, and separate structural, semantic and host/migration gates; no default activation or live calls during delivery.
+- Expose bounded returned-model metadata from the configured compatible adapter for acceptance without changing its request route or retaining hidden reasoning. Replace obsolete acceptance requirements for the legacy Gate/review chain with the current incremental contract.
+
+- Add read-only migration preflight and explicit private local backup/verification through existing inspection and control contracts. Preserve exact source/authority bytes, publish the checksum manifest last, refuse stale or active snapshots, and keep backup integrity distinct from production readiness. No automatic switching, restore, model calls or default changes.
+- Reuse strict processed-state reading in session lineage updates instead of overwriting damaged authority with an empty ledger. Surface managed-area enumeration and nonregular-file failures in bounded inspection.
+
+- Preserve runtime-maintenance partial outcomes when dependency/final observation fails, verify the final intended control bytes instead of accepting any new revision, and report uncertain write outcomes explicitly. Reuse the existing lossless receipt codec, budget retirement and replay contracts; no extra cleanup policy or model calls.
+
+- Add explicit, preview-first lossless terminal control-state compaction. Seal only proven completed run/commit receipts, preserve their exact decisions and cancellation behavior, and release active slots without deleting authorization. Keep bounded historical receipts readable through versioned, size-limited encoding; leave unresolved work and source/permission state intact.
+- Retain completed source-work budget counts under capacity pressure instead of evicting them and reopening the same work. Preserve legacy job ambiguity and independent new authorization; bound retired counters and reject damaged or oversized state. Default extraction routes, main prompt and package version stay unchanged.
+
+- Make public query completeness and Vault-wide pending progress explicit. Isolate malformed/duplicate records, use current Markdown for candidate lookup, freeze Todo query clocks across pages, and expose a read-only state-retention capacity inventory. No state collection, model calls, prompt changes or default pipeline activation.
+
+- Add opt-in incremental routing to existing text remember and MCP remember, using one typed user source and the shared selected-retention runner. Preserve caller policy, stable intent, source time, scope, cleanup isolation and zero-call recovery; retain legacy defaults.
+- Refuse damaged processed control state in both capture and execution instead of resetting authority and request evidence to an empty ledger.
+
+- Integrate the existing process/CLI/MCP/job entry points with an opt-in incremental automatic route. Preserve legacy defaults, stable capture addressing, frozen queue controls, two-request source budgets and zero-call commit recovery; retain partial write outcomes and expose read-only runtime health. No default activation or release.
+
+- Coordinate opt-in incremental scope discovery with frozen memory operations: preserve declared identities and explicit boundaries, write Markdown before missing registry nodes, and recover config/index/receipt failures without new model calls or duplicate writes. Version scope-dependent commit receipts while retaining legacy reads.
+
+- Add explicit bounded partial continuation on the existing incremental runner: zero-call exact container repair or one remaining changed-context replan. Preserve accepted operation IDs, source/authorization boundaries and original budgets; carry cumulative recovery receipts, cancel retained partial plaintext on Forget, and release resolved parent context protection. Default routes and the fixed prompt remain unchanged.
+
+- Add opt-in selected-source explicit retention on the canonical incremental runner: bind user intent and exact captured sources, keep unselected text as context, preserve automatic settlement, and recover with the shared two-request allowance. No default routing, prompt, model-setting or version change.
+
+- Connect configured native notes to opt-in incremental comparison using existing fragment identities, read-only NO_CHANGE targets and content/sharing guards. Keep native files and shadow maps untouched; disclose bounded selection and unavailable sources instead of assuming deduplication.
+- Protect pending incremental source context as well as its selected turn from cleanup, without claiming context as a new processing owner. No production-route, prompt, model-setting or version changes.
+
+- Reconcile the configured `process_incremental()` facade with the committed run-ID API and existing receipt schema; preserve one source-work budget, explicit transport recovery and cached-response recovery without model configuration.
+
+- Add an opt-in captured-turn incremental model runner on the shared G3b commit bridge. Persist request/response receipts, reuse source-work budgets with a two-dispatch ceiling, and recover saved responses without model regeneration. Do not switch production process/remember/MCP routes.
+- Fence concurrent legacy/incremental model workers without holding a file lock across provider calls; cancel in-flight receipts on Forget and preserve unresolved decisions without a second semantic review. Keep permanent-error and partial replanning boundaries explicit.
+
+- Stage explicit incremental apply/resume APIs on the shared MemoryWriter, freezing target groups, source/revision checks and NO_MEMORY/NO_CHANGE decisions. Default model routes remain unchanged.
+- Recover interrupted history/head/index/source-receipt work without reallocating IDs; protect staged sources from legacy re-extraction/cleanup and cancel shared-source pending plaintext before Forget.
+- Add 55 public commit/recovery regressions, including real process exit, concurrent replay and ten receipt-write fault boundaries. Preserve 187 existing tests; native comparison, new-scope transactions and model dispatch remain separate stages.
+
+- Add the staged, read-only incremental-items-v1 request/response compiler and Python preview API. Preserve target state with grouped patches, explicit scope/lifecycle checks and evidence-anchored calendar conversion. This does not enable a new production planner, call models, settle evidence or change package version.
+
+- Order known, non-overlapping source-turn windows before processing without changing capture IDs; advance only contiguous local receipt watermarks so capped batches and interrupted runs do not skip pending turns.
+- Reject ambiguous legacy job-budget migration for metadata-bearing sources rather than granting fresh allowance; merge proven legacy consumption even when a source-work row already exists.
+- Forward optional Hermes source metadata only from an exactly matched visible pair; keep missing timestamps unknown and bind revision-capable host IDs without reading tool or attachment content.
+- Remove the legacy summary instruction equating a completion report timestamp with the actual completion time. No model call, model-setting, package-version or release changes.
+
+- Repair source/intent contracts end to end: forward public remember intent, bind each authorization to immutable content/scope and original observation time, and keep separate authorizations in one host turn independent.
+- Preserve out-of-order initial messages, require trusted final for new source envelopes, and validate all immutable revision metadata even after inbox body cleanup.
+- Reconcile durable inbox receipts before selection/cleanup, fence commits against the actual source snapshot, retain revised evidence/coordination targets, and prevent duplicate retry selection.
+- Keep partial work eligible within its remaining budget; migrate exhausted legacy job counters without reopening authority. Version frozen input digests and reject unprovable legacy explicit-remember bindings instead of inventing timestamps.
+- Add 32 synthetic boundary regression tests. No extraction prompts, model settings, version, tags or release workflows changed.
+
+- Fix cross-namespace maintenance disposition fallback, provenance-sensitive semantic duplicates, and withdrawn-head leakage through project/priority/contextual retrieval.
+- Validate validity types before enum membership; keep malformed records from breaking unrelated reads. Retain pre-validity frozen UPDATE compatibility only for unchanged legacy-format targets.
+- Journal explicit retractions for bounded, revision-checked forward recovery; finish failed index work without duplicate history, preserve later edits, and cancel pending plaintext on forget.
+- Include public regressions in sdist, covering recovery boundaries, real subprocess exits, concurrency, old revisions and negative protocol cases. No model prompts, package version or release automation were changed.
+- Separate original `source_time` from local `captured_at`, persist stable message/revision/order metadata, use trusted final signals for new capture envelopes, and fence stale plans when a host message is revised.
+- Bind durable model-request budgets to source revisions plus explicit intent across synchronous/background transports. Completed authorization rows stay terminal, active rows are not age-evicted, and legacy over-limit counters remain exhausted instead of being reset.
+- Keep `completed_at` unknown unless evidence establishes an actual completion time; a message timestamp records observation, not the business event time.
+- Add a first-class `validity: valid|retracted` state. Deterministic retraction uses an expected revision, archives the previous valid body, keeps the stable current identity, and excludes retracted assertions from ordinary read/search/todo results while retaining explicit audit and forget paths.
+- Preserve completed and cancelled todo heads in `knowledge/` instead of retiring their stable identities by age. Add public deterministic contract tests to CI for legacy compatibility, retraction, revision conflicts, and closed-todo retention.
+
 ## 0.2.65 — 2026-09-16
 
 - Ground maintenance todo deadlines in Core-validated candidate evidence and `reference_time`. Relative calendar ranges resolve deterministically to their last valid day, while the normalized deadline view removes only formatting and equivalent parenthetical restatements without losing conflicting dates.

{memleaf-0.2.65 → memleaf-0.2.67}/MANIFEST.in

@@ -7,5 +7,8 @@ include README.en.md
 recursive-include examples *.md *.ndjson *.py
 recursive-exclude examples *_acceptance.py
 prune tests
+recursive-include tests_public *.py
 
 include docs/*.md
+
+include examples/incremental_acceptance.json

{memleaf-0.2.65/src/memleaf.egg-info → memleaf-0.2.67}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.65
+Version: 0.2.67
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -80,7 +80,8 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 - search 候选单页最多 20 项、约 4000 字符；
 - read 单页正文最多 2000 字符；
 - 同一受管理轮次可继续读取所有与问题相关的记忆；`read_count`/`read_chars` 仅用于审计，不再作为阻断配额；
-- `retrieval_id` 必须属于当前轮次，且必须先有成功的 `search` 才能 `read`；
+- 有宿主 Hook/Provider 时，`retrieval_id` 必须属于当前轮次；纯 MCP 客户端第一次 `search` / `list_todos` 可省略它，由 memleaf 返回短期 token，后续分页和 `read` 必须复用；
+- 无论哪种接入方式，都必须先有成功的 `search` / `list_todos` 才能 `read`；
 - `found`、`no_match` 和工具错误是不同状态，错误不能被伪装成无匹配；
 - `context()` 和 Python `search(view="full")` 作为兼容接口保留，但不属于自动检索路径。
 
@@ -96,6 +97,8 @@ memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assista
 - `UPDATE`：同一未来用途的现存记忆需要更新，沿用原 `memory_id`；旧内容进入 `history/`；
 - `NO_CHANGE`：只是重复、查询、临时状态、测试、审计、诊断或没有稳定复用价值，不新增记忆。
 
+普通事实被明确撤回但未要求彻底删除时，Core 可使用 `retract_memory()` 将同一 `memory_id` 标为 `validity: retracted`。旧有效正文进入 `history/`，普通 search/read/list_todos 不再把它作为当前事实；这与 `forget_memory()` 的物理删除合同不同。确定性撤回必须携带 `memory_revision()` 或 `read_page()` 返回的当前 `revision`，避免覆盖并发修改。完整边界见 [Memory state contract](docs/memory-state-contract.md)。
+
 额外约束：
 
 - 通常一轮产生 0～1 条记忆，而不是按句子拆分；
@@ -283,7 +286,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `rebuild_index` | 重建可重建的本地派生索引 |
 | `stats` | 返回 Vault 计数和诊断统计 |
 
-`search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一轮的 `retrieval_id` 完成 `search → read`；工具错误、Scope 冲突或读取预算耗尽都应如实处理。
+`search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一条检索链的 `retrieval_id` 完成 `search → read`。Hermes/Codex Hook 可直接提供该 token；只有 MCP 的客户端可在第一条 `search` / `list_todos` 省略 token，并使用返回值继续分页和读取。带 cursor 的后续页以及所有 `read` 都不能省略 `retrieval_id`。工具错误、Scope 冲突或读取失败都应如实处理。
 
 ## Python API
 
@@ -315,6 +318,8 @@ capture()             捕获可见事件
 process()             处理完整 inbox 轮次，需要模型路由
 remember()            显式保存，需要模型路由
 create_memory()       直接创建一条 Markdown 记忆
+memory_revision()     读取受保护内容的并发版本
+retract_memory()      撤回当前事实，保留同 ID 头和历史
 search()              本地检索，不更新命中统计
 context()             兼容接口，返回轻量目录
 read() / read_page()  读取记忆或分页正文
@@ -325,6 +330,12 @@ stats()
 compact()             按阈值整理低优先级记忆，需要模型路由
 ```
 
+`capture()` 可接收 `message_id`、`message_revision`、`source_sequence`、
+`previous_message_id`、`source_time` 和可信 `final` 信号。`source_time` 是带时区的
+原消息时间，缺失时保持未知，不会用本地 `captured_at` 冒充。`remember()` 的重试应
+复用同一 `intent_id`；新的明确保留授权使用新 ID。完整合同见
+[`docs/source-work-contract.md`](docs/source-work-contract.md)。
+
 离线示例默认使用临时 Vault，不写入 `~/.memleaf`，也不访问网络：
 
 ```bash
@@ -440,7 +451,7 @@ history:
 ```
 
 - active Markdown 每条最多保留 16 个来源明细，同时记录累计 `source_count`、`source_digest` 和省略数量，避免 UPDATE 让 `sources` 无限膨胀；
-- 已完成/已取消 todo 默认在 30 天后退出 `knowledge/` 并进入 `history/`；`list_todos(status=completed|cancelled|all)` 仍可枚举这些历史待办；
+- 已完成/已取消 todo 保留在 `knowledge/` 中作为稳定当前身份，默认 active 清单不展示，但 `list_todos(status=completed|cancelled|all)` 和后续维护仍可按原 ID 定位；`closed_todo_retention_days` 仅作为旧配置兼容项保留；
 - `history.policy: bounded` 默认每个稳定记忆身份最多保留 32 个完整历史版本，且超过 3650 天的版本可被维护流程淘汰；需要永久审计时可显式设置 `history.policy: keep_all`；
 - compaction 会保留一个既有 canonical `memory_id`，不会再为整理结果创建新的 `mem-compact-*` 身份；单条精简保持原 ID，多条合并选择一个稳定 survivor。
 - 这些维护动作在正常 `process()` / `remember()` / `compact()` 生命周期中执行，不需要 daemon；普通只读检索本身不触发维护写入。

{memleaf-0.2.65 → memleaf-0.2.67}/README.en.md

@@ -75,6 +75,8 @@ memleaf does not save every sentence. When a complete visible user + assistant t
 - `UPDATE`: an active memory for the same future use needs new information, so keep its `memory_id` and move the old version to `history/`;
 - `NO_CHANGE`: the turn is a duplicate, query, temporary state, test, audit, diagnostic, or otherwise has no stable reuse value, so append nothing.
 
+When an ordinary assertion is explicitly withdrawn without a request to erase it, Core can use `retract_memory()` to keep the same `memory_id` with `validity: retracted`. The prior valid body moves to `history/`, and ordinary search/read/list_todos no longer treats it as current fact. This is distinct from the physical-deletion contract of `forget_memory()`. A deterministic retraction must carry the current revision returned by `memory_revision()` or `read_page()` so it cannot overwrite a concurrent edit. See [Memory state contract](docs/memory-state-contract.md) for the complete boundary.
+
 Additional rules:
 
 - A normal turn typically produces 0–1 memory rather than one memory per sentence.
@@ -298,6 +300,8 @@ capture()             Capture a visible event
 process()             Process complete inbox turns; requires a model route
 remember()            Explicitly save a memory; requires a model route
 create_memory()       Directly create a Markdown memory
+memory_revision()     Read the protected-state concurrency revision
+retract_memory()      Retract an assertion while keeping its ID and history
 search()              Local retrieval without updating hit counts
 context()             Compatibility API returning a light directory
 read() / read_page()  Read a memory or a body page
@@ -308,6 +312,13 @@ stats()
 compact()             Compact low-priority memories; requires a model route
 ```
 
+`capture()` accepts `message_id`, `message_revision`, `source_sequence`,
+`previous_message_id`, `source_time`, and a trusted `final` signal. `source_time`
+is the timezone-aware original message time; when absent it remains unknown and
+local `captured_at` is never substituted. Retries of one explicit `remember()`
+authorization should reuse its `intent_id`; a new authorization uses a new ID.
+See [`docs/source-work-contract.md`](docs/source-work-contract.md).
+
 The offline example uses a temporary Vault by default. It does not write to `~/.memleaf` or access the network:
 
 ```bash
@@ -423,7 +434,7 @@ history:
 ```
 
 - Each active Markdown memory retains at most 16 detailed provenance rows while tracking cumulative `source_count`, `source_digest`, and omitted rows, so repeated UPDATEs cannot grow `sources` without bound.
-- Completed/cancelled todos leave `knowledge/` after 30 days by default and move to `history/`; `list_todos(status=completed|cancelled|all)` can still enumerate retired todos.
+- Completed/cancelled todos remain in `knowledge/` as stable current identities. The default active view hides them, while `list_todos(status=completed|cancelled|all)` and later maintenance can still resolve the original ID. `closed_todo_retention_days` remains only as a legacy configuration key.
 - With `history.policy: bounded`, each stable memory identity keeps at most 32 full historical versions, and versions older than 3650 days are eligible for pruning. Set `history.policy: keep_all` explicitly when permanent audit retention is required.
 - Compaction preserves an existing canonical `memory_id` instead of creating a new `mem-compact-*` identity; a single-memory rewrite keeps its ID and a multi-memory merge chooses one stable survivor.
 - Maintenance runs through normal `process()` / `remember()` / `compact()` lifecycle calls and requires no daemon. Ordinary read-only retrieval does not trigger maintenance writes.

{memleaf-0.2.65 → memleaf-0.2.67}/README.md

@@ -61,7 +61,8 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 - search 候选单页最多 20 项、约 4000 字符；
 - read 单页正文最多 2000 字符；
 - 同一受管理轮次可继续读取所有与问题相关的记忆；`read_count`/`read_chars` 仅用于审计，不再作为阻断配额；
-- `retrieval_id` 必须属于当前轮次，且必须先有成功的 `search` 才能 `read`；
+- 有宿主 Hook/Provider 时，`retrieval_id` 必须属于当前轮次；纯 MCP 客户端第一次 `search` / `list_todos` 可省略它，由 memleaf 返回短期 token，后续分页和 `read` 必须复用；
+- 无论哪种接入方式，都必须先有成功的 `search` / `list_todos` 才能 `read`；
 - `found`、`no_match` 和工具错误是不同状态，错误不能被伪装成无匹配；
 - `context()` 和 Python `search(view="full")` 作为兼容接口保留，但不属于自动检索路径。
 
@@ -77,6 +78,8 @@ memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assista
 - `UPDATE`：同一未来用途的现存记忆需要更新，沿用原 `memory_id`；旧内容进入 `history/`；
 - `NO_CHANGE`：只是重复、查询、临时状态、测试、审计、诊断或没有稳定复用价值，不新增记忆。
 
+普通事实被明确撤回但未要求彻底删除时，Core 可使用 `retract_memory()` 将同一 `memory_id` 标为 `validity: retracted`。旧有效正文进入 `history/`，普通 search/read/list_todos 不再把它作为当前事实；这与 `forget_memory()` 的物理删除合同不同。确定性撤回必须携带 `memory_revision()` 或 `read_page()` 返回的当前 `revision`，避免覆盖并发修改。完整边界见 [Memory state contract](docs/memory-state-contract.md)。
+
 额外约束：
 
 - 通常一轮产生 0～1 条记忆，而不是按句子拆分；
@@ -264,7 +267,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `rebuild_index` | 重建可重建的本地派生索引 |
 | `stats` | 返回 Vault 计数和诊断统计 |
 
-`search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一轮的 `retrieval_id` 完成 `search → read`；工具错误、Scope 冲突或读取预算耗尽都应如实处理。
+`search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一条检索链的 `retrieval_id` 完成 `search → read`。Hermes/Codex Hook 可直接提供该 token；只有 MCP 的客户端可在第一条 `search` / `list_todos` 省略 token，并使用返回值继续分页和读取。带 cursor 的后续页以及所有 `read` 都不能省略 `retrieval_id`。工具错误、Scope 冲突或读取失败都应如实处理。
 
 ## Python API
 
@@ -296,6 +299,8 @@ capture()             捕获可见事件
 process()             处理完整 inbox 轮次，需要模型路由
 remember()            显式保存，需要模型路由
 create_memory()       直接创建一条 Markdown 记忆
+memory_revision()     读取受保护内容的并发版本
+retract_memory()      撤回当前事实，保留同 ID 头和历史
 search()              本地检索，不更新命中统计
 context()             兼容接口，返回轻量目录
 read() / read_page()  读取记忆或分页正文
@@ -306,6 +311,12 @@ stats()
 compact()             按阈值整理低优先级记忆，需要模型路由
 ```
 
+`capture()` 可接收 `message_id`、`message_revision`、`source_sequence`、
+`previous_message_id`、`source_time` 和可信 `final` 信号。`source_time` 是带时区的
+原消息时间，缺失时保持未知，不会用本地 `captured_at` 冒充。`remember()` 的重试应
+复用同一 `intent_id`；新的明确保留授权使用新 ID。完整合同见
+[`docs/source-work-contract.md`](docs/source-work-contract.md)。
+
 离线示例默认使用临时 Vault，不写入 `~/.memleaf`，也不访问网络：
 
 ```bash
@@ -421,7 +432,7 @@ history:
 ```
 
 - active Markdown 每条最多保留 16 个来源明细，同时记录累计 `source_count`、`source_digest` 和省略数量，避免 UPDATE 让 `sources` 无限膨胀；
-- 已完成/已取消 todo 默认在 30 天后退出 `knowledge/` 并进入 `history/`；`list_todos(status=completed|cancelled|all)` 仍可枚举这些历史待办；
+- 已完成/已取消 todo 保留在 `knowledge/` 中作为稳定当前身份，默认 active 清单不展示，但 `list_todos(status=completed|cancelled|all)` 和后续维护仍可按原 ID 定位；`closed_todo_retention_days` 仅作为旧配置兼容项保留；
 - `history.policy: bounded` 默认每个稳定记忆身份最多保留 32 个完整历史版本，且超过 3650 天的版本可被维护流程淘汰；需要永久审计时可显式设置 `history.policy: keep_all`；
 - compaction 会保留一个既有 canonical `memory_id`，不会再为整理结果创建新的 `mem-compact-*` 身份；单条精简保持原 ID，多条合并选择一个稳定 survivor。
 - 这些维护动作在正常 `process()` / `remember()` / `compact()` 生命周期中执行，不需要 daemon；普通只读检索本身不触发维护写入。

memleaf-0.2.67/docs/acceptance-evidence-guide.md

@@ -0,0 +1,129 @@
+# Acceptance evidence guide — fixed candidate, separate gates
+
+This is an operator/evidence guide, not a new runtime, model prompt, test harness,
+or permission to change a live Vault. Keep the exact acceptance commit and its
+CI artifacts fixed while evaluating it. If an actual defect requires a code
+change, record a new commit and rerun affected gates; do not mix their results.
+
+## Gates and completion evidence
+
+| Gate | Evidence required | What it does not establish |
+|---|---|---|
+| Repository identity | Actual remote commit, full tree, parent, branch | Passing tests, installation or release |
+| Source and native artifacts | Source report; each existing native CI cell's wheel/sdist reports; matching commit, manifest, full test inventory and payload hashes | Real Hermes/Codex lifecycle or model semantic fidelity |
+| Deterministic requirement clauses | Original requirement, exact test method and assertions, executed evidence on the fixed candidate, explicit limitations | Entire requirement signed off merely because a related module ran |
+| Real installed host | Executable/version, copied Provider build, actual test Vault and effective routes, capture/final/source-time flow, reconnect, privacy and shared retrieval | Model quality based only on a stub response or tool discovery |
+| Live Flash semantics | Approved configured route, permitted suite and holdout provenance, total reservation limit, all attempted repetitions, structural results plus human/source-based semantic review | A JSON-only pass or exact provider billing from a reserved slot |
+| Controlled migration/rollback | Known writers actually stopped, verified current backup, retained authority and latest Forget boundary, isolated rehearsal | Automated restore, distributed consistency or production authorization |
+
+A test that intentionally expects a refusal validates that protection, not a
+successful extraction. NO_MEMORY may be correct, but cannot be used as a blanket
+way to eliminate necessary memories. Keep pending, scan completeness, semantic
+quality and successful writes separate. Never mark all FS001–FS200 complete from
+the suite count or from module-name references.
+
+## Current route semantics
+
+The v0.2.67 candidate has one processing engine: incremental. New Vaults default
+both `process.automatic_pipeline` and `process.remember_pipeline` to
+`incremental`. A retained `legacy` value from an older Vault is not executable;
+migration preflight reports it as `legacy_pipeline_configuration`, and runtime
+entry points reject it with `legacy_pipeline_removed`.
+
+A successfully installed candidate is still not proof that production migration is
+safe. Existing legacy queue/control records retain their identity for diagnosis and
+must be settled or explicitly reviewed; they are not reinterpreted as incremental
+work. Do not erase old work, failed receipts or request counters to obtain a clean
+preflight result.
+
+## Preparation with no paid calls
+
+Use the existing entry point on a known candidate installation:
+
+```sh
+python -m memleaf.acceptance --suite examples/incremental_acceptance.json --repeat 5
+```
+
+This is plan-only: it validates the suite and reports hashes and request bounds;
+it does not load a backend configuration or create a Vault. `process --dry-run`
+is different and may call the configured model. Do not use it as a free preview.
+
+The shipped suite is public synthetic regression material. Take case count, turn
+count, repetitions, normalized suite hash, prompt hash and request bounds from
+this command on the selected candidate; do not inherit numbers from an older
+report. Also record the original suite file SHA-256: it is not the normalized
+semantic suite hash. The reported bound is not a spending authorization. A private
+held-out suite requires its own provenance, permission and count. Merely adding
+a label `holdout` does not prove the examples were unseen in tuning.
+
+Do not execute until the actual route/model, local credential reference, suite
+hash, repeats and total allowance are approved. Keep credentials local. Do not
+paste API keys or credential-bearing URLs into chat, public issues or logs. All
+trials, including failed, interrupted and budget-limited ones, remain in the
+report. Starting a new output directory is not an unmetered retry.
+
+## Bind evidence without manufacturing a pass
+
+Keep an external acceptance record containing repository commit and tree, CI run
+and attempt, manifest digest, wheel/sdist digests, executed test inventory, exact
+requirement clauses, host identities, effective routes and suite/budget approval.
+A rerun has a new attempt; an assertion change has a new source identity even
+when test IDs/count are unchanged. Never substitute another attempt's missing
+stage report. A green workflow summary is not a replacement for the reports.
+
+A documentation-only follow-up still has a new repository tree and sdist bytes.
+Previous CI remains evidence for its original commit. Record that the runtime and
+test bytes are unchanged, but do not relabel that CI as a run of the follow-up.
+Do not overwrite a published artifact with a same-version development artifact.
+
+A requirement record should name its original assertion, tested subclause, exact
+test method, source digest, execution report, result and remaining boundary. A
+failed platform cell cannot be signed off because another platform passed.
+Classify untested semantic/host assertions explicitly rather than converting them
+to a static-code pass. Link any later repair to its new test evidence.
+
+## Host preparation and privacy
+
+Read the installed host's actual help and configuration; do not invent isolation
+flags. Inventory versions and safe effective settings before starting sessions.
+A host may make model requests during a session, so no live session or extraction
+is implied by a request for zero-call preparation. If host profiles cannot be
+isolated without touching production, stop that part and report the limitation.
+
+Prepare an independent environment and an empty synthetic test Vault only after
+its path and isolation are clear. Do not copy a formal Vault, native notes or
+real chat archive merely to make a fixture. Use synthetic native files for initial
+share/read-only tests. Private incident material must be separately approved.
+
+For real acceptance, source labels alone (`hermes`/`codex`) do not prove the actual
+host ran. Record actual process/configuration and behavior. Test one complete
+automatic turn as user input plus trusted final assistant reply; prove that a
+previous settled turn is not silently copied into the normal prompt, while the
+assistant's current-turn restatement can resolve a user's shorthand choice. Also
+test a genuinely non-self-contained turn and require conservative deferral rather
+than guessed history. Verify durable NO_MEMORY settlement, authentic available
+source metadata, final versus intermediate messages, stop-recording and late
+callbacks, shared search/read, repeat/new intent, same-ID state changes and
+restarts. Missing original time stays unknown, not fabricated.
+
+## Migration and release boundaries
+
+`migration_preflight()` is an observation. `writers_stopped=True` is an operator
+attestation, not process-discovery proof. Preflight/backup verification do not
+perform a full apply/restore or stop old programs. Known writer shutdown and
+reopening must be verified independently on the isolated installation.
+
+A valid old backup may contain content forgotten later. Do not restore it for
+service without preserving and applying the available later Forget/authority
+constraints under explicit permission. A code rollback that keeps current data
+and uses a verified compatible read path is not a full snapshot restore.
+
+Full destructive authority TTL, cross-Vault merge, general multi-ID semantic
+merge, automatic native-conflict resolution and cross-machine coordination
+remain outside the first-enabled scope. Keep those limits explicit; they cannot
+be reported as implemented features. Release/tag/version changes, main merge
+and production operations each retain their own authorization boundary.
+
+The [host acceptance runbook](host-acceptance-runbook.md) separates inventory,
+authorized sessions and cold-cutover rehearsal. It does not require a new
+installer, adapter or verification framework.