memleaf 0.2.25__tar.gz → 0.2.26__tar.gz

{memleaf-0.2.25 → memleaf-0.2.26}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.26 — 2026-09-05
+
+- Refactor automatic processing into explicit model execution, planning, update coordination, commit, journal and audit owners while preserving Markdown Vaults, memory IDs, Hermes MemoryProvider and cross-Agent retrieval contracts. No runtime dependency or independent service is added.
+- Remove post-Gate completion/rework generation, forced status/type/Scope rewrites, local last-retry candidate splitting, wrong-target UPDATE-to-CREATE conversion and automatic old/new body concatenation. Invalid proposals receive bounded model correction, then explicit candidate-local deferral; valid siblings proceed.
+- Add source-neutral exact evidence bindings and one bounded coverage correction. Assistant synthesis, recalled memory and truncated observations do not independently authorize new facts; evidence and candidate outcomes are accounted separately.
+- Reconcile compatible same-target updates into one model-owned write/history operation with all contributing receipts. Preserve actual outcomes on replay and reject stale target revisions under the shared Vault lock.
+- Freeze complete change payloads; explicit forget cancels matching pending operations before deletion. Explicit remember enforces selected Scope and target revisions. Automatic/explicit writes, forget, raw-library writes and compaction share the lock/recovery entry boundary without conflating their authorization.
+- Honor leading recording controls and record=False before persistence, consume only safely captured tool caches, and retry unresolved coverage at most once through natural lifecycle triggers. Keep unresolved source evidence after exhaustion.
+- Unify bounded/metadata/off tool-evidence retention across direct capture, Hermes, Codex and planning. Preserve legacy disabled settings and document-source exclusions; configuration changes do not fabricate missing source content.
+- Add read-only audit, isolated dry-run, Windows native process-liveness and cross-process file-lock safeguards. Run complete regression suites on Linux, Windows and macOS plus wheel/sdist installation checks.
+- Deterministic contract tests do not establish real-model semantic quality. The maintainer selected local live-model acceptance rather than repository model credentials; no real-model result is claimed by this release.
+
 ## 0.2.25 — 2026-09-04
 
 - Keep global todo questions and cross-session recaps strictly read-only,

{memleaf-0.2.25 → memleaf-0.2.26}/MANIFEST.in

@@ -8,3 +8,5 @@ include RELEASE_CHECKLIST.md
 include IMPLEMENTATION_PLAN.md
 recursive-include tests *.py
 recursive-include examples *.md *.ndjson *.py
+
+include docs/*.md

{memleaf-0.2.25/src/memleaf.egg-info → memleaf-0.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.25
+Version: 0.2.26
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,8 +23,8 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.25。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.25 通过 PyPI 分发。
+> **版本：0.2.26。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版完成共享记忆核心重构；真实模型语义效果仍需结合本地模型和业务样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -421,7 +421,7 @@ $HOME/.memleaf/
 
 ## 隐私与安全边界
 
-- 捕获默认只接收调用方明确传入的 user/assistant 可见文本；不捕获 system prompt、developer prompt、隐藏推理、原始工具输出或附件全文；
+- 对话捕获只接收 user/assistant 可见文本，不捕获 system/developer 指令或隐藏推理。匹配到当前轮工具调用的证据另由 `capture.tool_evidence_mode` 控制；新建 Vault 默认 `bounded`（脱敏、有界正文），文件/附件正文默认不留存。旧配置显式关闭工具输出时不自动升级为保留正文；
 - 捕获落盘前尽力脱敏常见 API key、Bearer token、Cookie、JWT 和私钥，但脱敏不是加密，也不能保证识别所有敏感信息；
 - 路径校验、符号链接检查、Vault 锁、同目录临时文件、fsync 和原子替换用于保护本地写入；
 - memleaf 不主动上传整个 Vault，也没有托管后台、遥测或账号系统；
@@ -466,3 +466,46 @@ MIT，见 [LICENSE](LICENSE)。
 
 **memleaf**
 *Your memories, in files you own.*
+
+
+## 通用处理与只读验收（0.2.26）
+
+邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
+自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。
+模型负责语义判断，代码验证来源和原文引用。通过引用校验并不保证模型的语义判断一定正确。
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+`audit` 完全本地、只读，不调用模型，不推断旧记忆由哪个版本创建，也不自动清理。
+`--dry-run` 在私有临时副本运行正常处理，可能调用配置的独立 Model Route；不会改写原 Vault。
+检测到原 Vault 并发变化时会拒绝输出可用预览。没有一键应用预览的功能。
+
+工具执行状态与证据完整性分别记录；超限、丢失或不完整内容不会被模型的 NO_CHANGE 升级为完整。
+执行成功但尚有未解决项时，结果显示 `coverage_status=partial`，并保留来源以供有界重试或补充证据。
+行为、限制、测试协议变更见 [通用处理说明](docs/general-processing.md)。
+
+### 工具证据留存配置
+
+```yaml
+capture:
+  tool_evidence_mode: bounded  # bounded | metadata | off
+  include_attachments: false
+```
+
+`bounded` 允许当前轮真实工具观察保留有界、脱敏的正文；小结果可能完整保留，
+不是承诺只保存模型总结。`metadata` 仅留工具调用标识等元数据（仍可能包含标题），
+不保留证据正文，也不把主动排除误报成提炼漏项。`off` 不保存工具证据记录。
+三种模式均不允许把助手复述或旧记忆回读变成独立的新事实。
+
+现有配置未提供新字段时，旧 `include_tool_output: false` 或未设置该开关均按
+`metadata` 处理，旧 `true` 按 `bounded` 处理。显式新字段优先；新建 Vault 只写
+新字段，不再同时写含义冲突的旧开关。`include_attachments: true` 仍受上述总模式限制。
+宿主通过结构化文件路径、文件/附件标识识别文档；不承诺识别任意 Shell 命令或不透明工具
+隐藏读取的文件。用户粘贴的可见文档和显式 `remember` 内容不属于自动附件抓取。
+
+策略在待捕获缓存、inbox 写入和新模型提炼输入处共同执行。配置收紧不会自动删除已提交
+记忆或改写已捕获 inbox；失败前已经冻结的提交计划也不作为新的模型调用重新提炼。
+已捕获工具原文的清理仍遵守原有安全期，明确忘记使用 `forget_memory/forget_about`。

{memleaf-0.2.25 → memleaf-0.2.26}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.25.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.25 is distributed through PyPI.
+> **Version: 0.2.26.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. This version completes the shared memory core refactor; real-model semantics still require local acceptance with the selected model and representative inputs.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -404,7 +404,7 @@ Directories are normally created with mode `0700`, and files are stored as plain
 
 ## Privacy and security boundaries
 
-- By default, capture accepts only explicitly supplied visible user/assistant text; it excludes system prompts, developer prompts, hidden reasoning, raw tool output, and full attachment bodies.
+- Conversation capture accepts visible user/assistant text, never system/developer instructions or hidden reasoning. Matched current-turn tool evidence is controlled separately by `capture.tool_evidence_mode`: new Vaults use bounded/redacted observations; document/attachment bodies are excluded by default. Legacy configurations disabling tool output are not silently opted into body retention.
 - Common API keys, Bearer tokens, cookies, JWTs, and private keys are redacted on a best-effort basis before capture is written. Redaction is not encryption and cannot detect every secret.
 - Path validation, symlink checks, Vault locks, same-directory temporary files, fsync, and atomic replacement protect local writes.
 - memleaf does not upload the entire Vault and has no hosted backend, telemetry, or account system.
@@ -450,3 +450,48 @@ MIT; see [LICENSE](LICENSE).
 **memleaf**
 
 *Your memories, in files you own.*
+
+
+## General processing and read-only inspection (0.2.26 candidate)
+
+Dialogue, calendars, tickets, files, web results and other tools share the evidence, coverage and write path.
+Models interpret semantics; Core validates physical provenance and exact original quotations.
+A valid quotation establishes provenance, not the truth or entailment of a generated claim.
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+Audit is local/read-only, never calls a model, never infers producing versions and never repairs automatically.
+Dry-run executes the normal processor on a private temporary copy and may call the configured Model Route.
+It does not modify the source Vault; concurrent source changes invalidate the preview. There is no apply-preview mode.
+Execution success is separate from evidence completeness: `coverage_status=partial` reports unresolved work.
+See [general processing](docs/general-processing.md) for the protocol, limits and verification boundaries.
+
+### Tool-evidence retention
+
+```yaml
+capture:
+  tool_evidence_mode: bounded  # bounded | metadata | off
+  include_attachments: false
+```
+
+`bounded` keeps bounded, redacted current-turn observations; small tool results may be
+retained in full, not just as model summaries. `metadata` keeps identifiers and permitted
+metadata (which may include titles), not bodies; intentional exclusions are not reported
+as unresolved extraction. `off` retains no tool-evidence records. None of these modes makes
+assistant synthesis or retrieved old memory independent evidence of new facts.
+
+For an existing file without the new mode, legacy `include_tool_output: false` or an
+absent boolean means `metadata`; true means `bounded`. An explicit new mode takes
+precedence. New Vaults write only the new mode. Attachment opt-in remains subject to the
+mode. Adapters classify structural file paths, file IDs and attachment handles, not
+arbitrary opaque shell commands. Pasted visible documents and explicit remember text
+are not automatic attachment capture.
+
+The policy applies to pending cache, inbox writes, and new model-planning inputs.
+Tightening it is not a retroactive rewrite of committed memories or captured inbox files.
+Previously frozen operations are recovered as existing plans, not new model calls.
+Captured evidence retains its existing cleanup grace period; use explicit forget for
+memory deletion. See `docs/evidence-retention.md` for limits and scope.

{memleaf-0.2.25 → memleaf-0.2.26}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.25。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.25 通过 PyPI 分发。
+> **版本：0.2.26。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版完成共享记忆核心重构；真实模型语义效果仍需结合本地模型和业务样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -402,7 +402,7 @@ $HOME/.memleaf/
 
 ## 隐私与安全边界
 
-- 捕获默认只接收调用方明确传入的 user/assistant 可见文本；不捕获 system prompt、developer prompt、隐藏推理、原始工具输出或附件全文；
+- 对话捕获只接收 user/assistant 可见文本，不捕获 system/developer 指令或隐藏推理。匹配到当前轮工具调用的证据另由 `capture.tool_evidence_mode` 控制；新建 Vault 默认 `bounded`（脱敏、有界正文），文件/附件正文默认不留存。旧配置显式关闭工具输出时不自动升级为保留正文；
 - 捕获落盘前尽力脱敏常见 API key、Bearer token、Cookie、JWT 和私钥，但脱敏不是加密，也不能保证识别所有敏感信息；
 - 路径校验、符号链接检查、Vault 锁、同目录临时文件、fsync 和原子替换用于保护本地写入；
 - memleaf 不主动上传整个 Vault，也没有托管后台、遥测或账号系统；
@@ -447,3 +447,46 @@ MIT，见 [LICENSE](LICENSE)。
 
 **memleaf**
 *Your memories, in files you own.*
+
+
+## 通用处理与只读验收（0.2.26）
+
+邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
+自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。
+模型负责语义判断，代码验证来源和原文引用。通过引用校验并不保证模型的语义判断一定正确。
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+`audit` 完全本地、只读，不调用模型，不推断旧记忆由哪个版本创建，也不自动清理。
+`--dry-run` 在私有临时副本运行正常处理，可能调用配置的独立 Model Route；不会改写原 Vault。
+检测到原 Vault 并发变化时会拒绝输出可用预览。没有一键应用预览的功能。
+
+工具执行状态与证据完整性分别记录；超限、丢失或不完整内容不会被模型的 NO_CHANGE 升级为完整。
+执行成功但尚有未解决项时，结果显示 `coverage_status=partial`，并保留来源以供有界重试或补充证据。
+行为、限制、测试协议变更见 [通用处理说明](docs/general-processing.md)。
+
+### 工具证据留存配置
+
+```yaml
+capture:
+  tool_evidence_mode: bounded  # bounded | metadata | off
+  include_attachments: false
+```
+
+`bounded` 允许当前轮真实工具观察保留有界、脱敏的正文；小结果可能完整保留，
+不是承诺只保存模型总结。`metadata` 仅留工具调用标识等元数据（仍可能包含标题），
+不保留证据正文，也不把主动排除误报成提炼漏项。`off` 不保存工具证据记录。
+三种模式均不允许把助手复述或旧记忆回读变成独立的新事实。
+
+现有配置未提供新字段时，旧 `include_tool_output: false` 或未设置该开关均按
+`metadata` 处理，旧 `true` 按 `bounded` 处理。显式新字段优先；新建 Vault 只写
+新字段，不再同时写含义冲突的旧开关。`include_attachments: true` 仍受上述总模式限制。
+宿主通过结构化文件路径、文件/附件标识识别文档；不承诺识别任意 Shell 命令或不透明工具
+隐藏读取的文件。用户粘贴的可见文档和显式 `remember` 内容不属于自动附件抓取。
+
+策略在待捕获缓存、inbox 写入和新模型提炼输入处共同执行。配置收紧不会自动删除已提交
+记忆或改写已捕获 inbox；失败前已经冻结的提交计划也不作为新的模型调用重新提炼。
+已捕获工具原文的清理仍遵守原有安全期，明确忘记使用 `forget_memory/forget_about`。

memleaf-0.2.26/docs/core-refactor.md

@@ -0,0 +1,129 @@
+# Shared memory core — controlled refactor
+
+Baseline: `bc7622e0f4c5c7b6658336c4deb71fce6a370f11` (the unreleased 0.2.26
+candidate). This document describes the completed four-increment design, not
+an assertion that arbitrary model outputs are correct. The maintainer chose to
+perform live-model acceptance locally; scripted fixtures are contract tests.
+
+## Product boundaries
+
+Markdown in `knowledge/` and `history/` remains the permanent source of truth.
+Existing Vaults, paths, frontmatter, memory IDs and public tools remain compatible.
+No database, vector engine, model weights, queue service, daemon, telemetry or
+third-party runtime dependency is introduced. The existing host-managed stdio
+MCP subprocess remains supported; no separate service needs deployment.
+
+Hermes still registers `MemleafMemoryProvider` with the official plugin API.
+Native MEMORY.md / USER.md stay read-only cooperating sources. Hermes and Codex
+use the same Core and selected Vault. Source/session identifiers describe
+provenance and lifecycle, never permanent-memory visibility. Scope Map -> search
+-> selected read, retrieval enforcement levels, budget, global todo paging,
+installation and the independent Model Route remain intact.
+
+## Ownership
+
+| Component | Responsibility |
+| --- | --- |
+| Processor | Orchestrate process/remember, compose components explicitly |
+| ModelExecutor | Existing Model Route, bounded correction, diagnostics |
+| PlanningContext | Read related memories, Scope evidence and target context |
+| MemoryPlanner | Validate model proposals and construct change requests |
+| UpdateCoordinator | One bounded reconciliation for an exceptional same-target group |
+| MemoryCommitter | Validate revisions, freeze/execute writes, coordinate forget cancellation |
+| ProcessJournal | Claims, progress, temporary evidence cleanup and retained retry state |
+| TurnAudit | Per-candidate/evidence outcomes and uncommitted lookup overlay |
+| recording_policy | Pre-capture permission controls, no business extraction |
+| evidence_policy | One retention rule for capture, host caches and new planning |
+
+There is one automatic pipeline, not parallel old/new writers, mixin inheritance
+or a dynamic attribute proxy. `Memleaf._mutation_boundary()` is the common Vault
+lock plus interrupted-compaction recovery boundary for automatic/explicit
+commits, raw-library writes, forget and compaction snapshot/commit. Each operation
+retains its own authorization, revision checks and journal. Models execute outside
+this critical section. Pending automatic writes are NOT replayed by entering the
+boundary: forget must be able to cancel them first.
+
+## Semantic ownership
+
+The model selects type, Scope, target and content. Deterministic code validates
+identity, allowed source spans, schema, explicit constraints and local conflicts.
+It can reject a proposal, but must not silently change its business meaning.
+
+Removed paths include completion/rework post-Gate candidate factories, forced
+summary status/timestamp insertion, keyword-based fact/project/todo conversion,
+last-retry Scope reassignment, local splitting of rejected candidates, formal-plan
+preference that changes type, and old/new body concatenation. A persistent wrong
+UPDATE target is DEFERRED, not converted into CREATE. Valid sibling candidates
+continue. The model may correct its proposal during bounded retries.
+
+`NO_CHANGE` remains a valid no-write decision. Missing required todo-update state
+is returned for model correction, not guessed locally. A model-declared ambiguous
+target can be represented as coverage DEFERRED / target_ambiguous. An exact title
+lookup with more than one target cannot select one. Source-local rejection and
+retrieval heuristics remain conservative checks, not a guarantee of semantic
+entailment. Only exact full-statement matching is used for legacy unbound outputs.
+
+For an UPDATE, the model must return the complete intended current state, retaining
+still-valid facts and omitting retired facts. Code no longer appends old paragraphs
+to an incomplete summary. The prior complete version is preserved in history.
+Real-model quality still needs local evaluation, including preservation of old
+facts and recognition of new assertions mixed with questions.
+
+Multiple admitted updates to one target are reconciled using the existing Model
+Route and original target revision. One compatible summary produces one write and
+one history record with all contributing receipts. True conflicts defer the group;
+unrelated targets proceed. Single updates incur no group call. Oversized groups
+are retained, not split into competing writes. Scope-retirement/native-shadowing
+authorizations are not silently combined.
+
+## Lifecycle and privacy
+
+Capture preserves process-owned root journal fields. Frozen requests keep complete
+payloads and checksums; recovery uses the saved payload without another model call.
+Revision checks under lock refuse stale overwrites. Replay preserves the actual
+CREATE/UPDATE outcome for each contributing candidate. This is forward recovery,
+not a database-style atomic transaction across every file in a Vault.
+
+Explicit forget cancels matching frozen operations before deleting files. Unrelated
+siblings survive, stale cancelled owners cannot commit, and a new explicitly
+authorized remember event can store the fact again. No permanent topic blacklist
+is added. Explicit remember skips value classification, not its supplied Scope or
+target-revision constraints.
+
+Successfully captured tool cache records are consumed only after their presence in
+inbox is confirmed. Failed capture retains evidence; historical loss cannot taint
+unrelated future turns. Retention modes and old-config compatibility are specified
+in `evidence-retention.md`. Historical abandoned cache entries are not globally
+purged as part of upgrade; no destructive migration is performed.
+
+Leading recording controls and `record=False` suppress user/assistant/tool content
+before persistence. Session off/resume state survives rebuild/restart, and late
+callbacks for private turns remain private. Examples and quoted controls cannot
+change permission. The command vocabulary is intentionally bounded (for example
+`这段不要记录`, `接下来不要记录`, `恢复记录`, `Don't record this`, `stop recording this session`);
+this is not arbitrary-language privacy inference. Integrations may use record=False.
+Permission state stores only booleans and hashed identifiers, never private text.
+
+Coverage-unresolved evidence receives at most one subsequent natural retry, capped
+to four old turns per process call alongside new complete work. Missing-source,
+Scope/target and ownership ambiguities wait for relevant new information or explicit
+retry instead of spending model budget forever. Exhaustion retains unresolved input.
+
+## Validation and test-contract migration
+
+The existing suite is retained. Renamed tests distinguish a MODEL correcting its
+Scope/type/target from the removed local repair. Public outcomes remain checked:
+stable ID, complete new content, one prior history version, no wrong-Scope write,
+retained inbox and independent sibling progress. Prior tests that expected invalid
+proposals to be rewritten now assert bounded model correction or explicit DEFERRED.
+
+A test that required creation of a fact absent from its input and attached to an
+unrelated target now requires zero writes; the valid duplicate sibling remains
+unchanged. Ambiguity fixtures explicitly return evidence-level DEFERRED and assert
+retention, rather than relying on plan-title keywords. Dedicated raw-response tests
+cover malformed evidence and illegal targets without the fixture binding adapter.
+
+Final-source testing must include the full Linux, Windows and macOS matrix, wheel
+entry points and the matching sdist suite. Native CLI registration is not live
+semantic acceptance. Test results are tied to exact commits/artifacts, not to a
+mutable local worktree or a percentage-complete estimate.

memleaf-0.2.26/docs/evidence-retention.md

@@ -0,0 +1,58 @@
+# Shared tool-evidence retention — refactor phase 3
+
+One deterministic policy governs direct capture, HostRuntime hooks and the copied
+Hermes MemoryProvider. It grants no semantic write permission and adds no service,
+runtime dependency, storage engine or model call.
+
+## Modes and compatibility
+
+| Effective setting | Bodies | Observation metadata |
+| --- | --- | --- |
+| bounded | Redacted, bounded | Retained |
+| metadata | Excluded | Retained |
+| off | Excluded | Excluded |
+
+New Vaults explicitly choose bounded; existing files without a mode preserve the
+legacy boolean (false/absent -> metadata, true -> bounded). An explicit new mode
+wins over the legacy boolean. Invalid strings and non-boolean flags fail closed.
+Loading config does not rewrite it. Normal saves make the effective mode explicit.
+
+The inherited limits remain eight records, 2,000 characters per body, and 320 per
+metadata field. Oversized eligible evidence remains incomplete; its prefix is
+never promoted into a complete fact. Policy-excluded observations are marked
+retention=metadata, have no content, and are not retried as missing evidence.
+No later relaxation recreates discarded original content.
+
+Document/attachment bodies require include_attachments=true and bounded mode.
+HostRuntime and the standalone Hermes adapter classify structural file arguments
+using the same tested contract (path/file_path/file_id/attachment_id/file URI,
+including bounded nesting). This is not a claim to identify every file hidden
+behind arbitrary terminal commands or undocumented remote tools. Direct callers
+must truthfully identify document evidence with source_type=document.
+
+## Lifecycle
+
+- Pre-capture recording permission takes precedence over every retention mode.
+- New host observations and pending-cache reads obey the effective mode.
+- Core capture validates and reapplies it before inbox persistence.
+- New planning calls filter evidence from already captured inbox events too,
+  without mutating the original event identity or frozen-plan input checksum.
+- Successful capture consumes only evidence verified in inbox under the same
+  policy; failed capture does not discard eligible observations.
+- No retrospective deletion of knowledge/history/inbox is implied. Frozen plans
+  already prepared before a policy change recover via their existing contract.
+  Explicit forget coordinates cancellation; a retention toggle is not forget.
+- Old abandoned host sessions are not scanned by a daemon or globally purged.
+  Current sessions consume their caches through the normal lifecycle.
+
+Metadata is not anonymization: identifiers/titles may remain sensitive. Redaction
+is best effort and local plaintext backups remain the user's responsibility.
+
+## Verification
+
+Contract tests cover legacy/no-capture config compatibility, round trips, explicit
+precedence, denied documents, shared Hermes/core classification, bounded redaction,
+cache-policy changes, direct and MCP fields, no model input after tightening,
+no false coverage/retry from deliberate exclusion, and no reconstruction on opt-in.
+Existing general evidence, native memory, lifecycle, retrieval and packaging tests
+remain part of the full suite; no live model credentials are required here.

memleaf-0.2.26/docs/general-processing.md

@@ -0,0 +1,161 @@
+# General processing reliability contract — 0.2.26 candidate
+
+This is source-neutral processing, not a mail extractor. Dialogue, documents,
+calendars, issue trackers and terminal/tool observations use the same admission
+and commit boundaries. No tool/topic keyword grants write permission.
+
+## Evidence and semantic decisions
+
+The host supplies physical user events or actual matched current-turn tool
+call/results. Assistant synthesis, a caller-supplied digest, and read-back of
+memleaf knowledge cannot independently authorize new writes. Standard memleaf
+resource names and explicit paths into the current Vault are treated as
+read-back, including aliased filesystem tools. Undeclared/relative resources
+cannot always be identified; adapters must supply meaningful resource identity.
+
+Evidence inventory IDs depend on captured event/source locations, not candidate
+numbering or unrelated inventory order. User origin/syntax labels are hints,
+not the final semantic classification. One example request does not mark an
+independent real assertion as hypothetical. Actual pasted documents/code may
+be evidence; examples, suggestions and hypothetical content are not new facts.
+
+The Gate still decides future value, entailment, semantic role, ownership and
+CREATE/UPDATE/NO_CHANGE. Each writable candidate quotes actual evidence units.
+Core validates the unit/event identity, physical source, exact text and bounds.
+Start/end are relative to unit.text; they may both be omitted for a unique exact
+quotation, in which case Core locates it without model character counting.
+Malformed/ambiguous references fail the contract. Matching a quote proves
+provenance, not semantic truth. This mechanism is not a universal NLP proof.
+
+Legacy candidate-only output has no n-gram or short-text authorization bypass.
+It must repeat a complete non-query source statement, or produce an explicit
+validated quotation via the bounded correction path. Automatic summarization
+sees only admitted spans, candidate semantics and the bounded existing-target
+context. Its source references must stay within admitted event keys. Final
+scope/type/target/date checks remain active.
+
+## Coverage, limits and no-op behavior
+
+A Gate may map multiple facts in one evidence unit to several candidates, or
+one candidate to several units. Coverage is checked against real supplied IDs.
+One source-neutral correction can classify missing units; its candidates pass
+the same validator/deduplication path, never a post-Gate business-pattern writer.
+Already valid siblings survive a malformed correction. Work that remains
+ambiguous is retained and explicitly reported, not guessed into a global scope.
+
+Evidence decisions, candidate dispositions and filesystem operations are
+separate ledgers. `execution_status=ok` is not complete extraction:
+`coverage_status=partial` plus `unresolved_evidence_count` describes remaining
+work. Known incomplete/missing observations remain unresolved even when a model
+labels them NO_CHANGE. Incomplete turns retain their source instead of being
+cleaned after the usual grace period. Scope-filtered retries may revisit them;
+no endless automatic model retry or extra external tool call is introduced.
+
+Tool evidence is bounded to eight records with at most 2,000 content characters
+per captured result record and 320-character metadata fields, with redaction at
+Core capture. Large unambiguous top-level record collections retain complete
+records and enclosing context within that budget. Per-record provenance takes
+precedence over common source metadata. An overflow slot reports omitted
+records. Arbitrary large prose is not split into falsely complete facts;
+unsupported/incomplete content needs a supported complete source excerpt or a
+later source input. Execution outcome and completeness are distinct.
+
+Codex pending tool data retains sixteen turns; bounded tombstones make evicted
+uncaptured evidence visible as incomplete. Older loss beyond 256 tombstones
+leaves a session diagnostic only; it does not mark unrelated future turns as
+incomplete. Successfully captured observations are consumed from the host cache.
+No old observation is attached as a new fact to a different turn.
+
+Automatic NO_CHANGE does not modify permanent Markdown, sources or history.
+Processing watermarks/diagnostics may still advance: these are not permanent
+memory ownership. Existing native-memory coexistence, global shared Vault
+visibility and Scope Map/search/read contracts remain unchanged.
+
+## Commit and recovery
+
+Final requests, source identifiers, candidate/evidence decisions and scope
+operations are frozen to a checksum-protected local plan before mutation.
+Limits are 8 MiB per plan and 16 MiB for the pending plan inventory. No raw tool
+transcript is duplicated into the plan. Plans contain the final memory payload,
+which remains private Vault data. A checksum detects corruption, not a malicious
+local filesystem owner.
+
+Under the existing Vault lock, current target revisions are checked before
+commit. A stale update cannot overwrite another agent's change. Exact
+commit-time duplicates include title and complete state-bearing content, so two
+independent titled tasks are not merged solely because their bodies match.
+Model-assisted same-future-use matching still uses bounded existing candidates;
+it is not replaced with fuzzy string authorization or embeddings.
+
+A retry resumes a matching persisted plan without asking the model for a new
+summary. CREATE/UPDATE outcomes survive interrupted final-ledger writes.
+Explicit cross-project correction and retirement preserve their original
+history identity and do not resurrect the wrong target on replay. Ordinary
+cross-project target selection does not inherit this special authorization.
+Conflicting same-turn writes to one target are deferred/rejected rather than
+silently applied in sequence. This remains forward recovery, not a database
+transaction across the whole Vault filesystem.
+
+## Read-only inspection
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+Audit is local, creates no source lock/index and makes no model call. It reports
+verifiable identical active payloads and invalid/pending accounting; it does not
+infer which release produced old data or automatically delete/repair anything.
+
+Dry-run executes the normal processor on a private temporary copy. It can call
+the configured independent Model Route and read configured native sources, but
+never writes them or the original Vault. It returns candidate decisions and
+knowledge/history changes, not configuration credentials. The copy is deleted.
+Snapshots are limited to 256 MiB/100,000 relevant files, reject symlinked children
+and compare original content before/after. Concurrent source changes invalidate
+the preview. There is deliberately no apply-preview command.
+
+## Verification boundaries
+
+Deterministic backends test schema and filesystem behavior, not hosted-model
+accuracy. tests/semantic_fixtures.py adapts prescribed old Gate judgments to the
+quote protocol for update/history/maintenance tests. It does not run in product
+code and is not proof those judgments are semantically sound. New adversarial
+protocol tests choose their quotations explicitly. No model score or absolute
+"all languages/all scenarios" accuracy claim is made.
+
+Before release, separately inspect live Model Route behavior on held-out real
+shaped inputs, without writing the real Vault. Validate pure queries, mixed
+assertions/questions/examples, negation, user confirmations, multilingual
+paraphrases, multiple scopes and several external tool categories. Record actual
+model/provider, counts of false writes/omissions/deferrals, and failures without
+including credentials or private transcripts. Unit-test success cannot replace
+that acceptance.
+
+## Native Windows verification boundaries
+
+Windows processing-owner liveness is queried through a process handle with
+SYNCHRONIZE access, never by sending a signal. Shared-Vault writes use a
+native byte-range lock between processes, not only a Python thread mutex.
+Native child-process tests run on Linux, macOS and Windows.
+
+The full Python suite runs on all three OS families. Only the `install.sh`
+shell-harness class is POSIX-only; Windows retains installation, upgrade,
+PowerShell syntax, host lifecycle and native Codex acceptance. Test launchers
+use native `.cmd` wrappers on Windows. Byte-preservation assertions compare
+actual before/after bytes, including CRLF. POSIX mode-bit checks are conditional:
+Windows file privacy follows the Vault directory's inherited ACLs, and Unix
+`0600` must not be interpreted as proof of a Windows owner-only DACL.
+
+Real-model acceptance requires an explicit model route in repository Actions:
+secret `MEMLEAF_LIVE_MODEL_TOKEN` and variables `MEMLEAF_LIVE_BASE_URL` and
+`MEMLEAF_LIVE_MODEL`. Missing configuration is a blocked acceptance result,
+not a passing semantic test. Never publish based only on deterministic mocks.
+
+## Capture policy (shared-core refactor)
+
+Tool evidence is controlled by `capture.tool_evidence_mode` and document opt-in,
+not the presence of business words. The same policy runs before cache/inbox writes
+and new model-planning calls. Intentional exclusion is not missing evidence.
+See [retention contract](evidence-retention.md) for legacy settings, plaintext
+metadata, opaque-resource limitations and the distinction from explicit forget.