memleaf 0.2.31__tar.gz → 0.2.32__tar.gz

{memleaf-0.2.31 → memleaf-0.2.32}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.32 — 2026-09-07
+
+- Add bounded `unknown_unit` Gate diagnostics that identify the exact response field and retain only allowlisted type/length/digest and expected-set summaries; raw invalid values, legal ID lists and model output remain excluded from normal logs and failed state.
+- Give bounded correction attempts the failed constraint, field path and immutable legal-ID inventory used by validation, so coverage and evidence-binding references are repaired by regeneration rather than host-side ID substitution or relaxed evidence authority.
+- Keep `invalid_evidence` compatibility, source-neutral physical evidence boundaries, and watermark/cleanup safety unchanged: a persistently failed Gate does not advance the watermark or trigger cleanup.
+
 ## 0.2.31 — 2026-09-07
 
 - Unify Core and the copied Hermes provider on one idempotent UTF-8 evidence budget: at most 64 source records, 32 KiB per body, and 128 KiB of aggregate body text. Complete matched sources above the former 2,000-character/eight-record limits remain available within those bounds.

{memleaf-0.2.31/src/memleaf.egg-info → memleaf-0.2.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.31
+Version: 0.2.32
 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.31。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版统一 Core 与 Hermes Provider 的 UTF-8 证据留存预算：最多 64 条 source records、每条正文 32 KiB、正文总量 128 KiB，并保留有界 loss markers 与幂等规范化；同时将 metadata 模式下成功捕获的超限 pending 证据按相同有效策略消费。Gate 继续使用 physical evidence projection、`candidates`、`coverage`、`evidence_bindings` 和 allowlisted `evidence_check` 诊断，保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
+> **版本：0.2.32。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版在既有 UTF-8 证据留存预算和 metadata pending 消费策略上，为 Gate 的 `unknown_unit` 提供字段路径、类型/长度/摘要和期望集合摘要等受限诊断，并在同一合法 ID 清单约束下最多三次尝试、最多两次纠正；不记录原始值、不做 ID 猜测，持续失败不推进水位且不触发清理。保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -490,7 +490,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.31）
+## 通用处理与只读验收（0.2.32）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。

{memleaf-0.2.31 → memleaf-0.2.32}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.31.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. This release unifies Core and the Hermes provider on an idempotent UTF-8 evidence budget: at most 64 source records, 32 KiB per body, and 128 KiB of aggregate body text, with bounded loss markers; metadata-mode pending evidence from an oversized observation is consumed after successful capture under the same effective policy. The Gate still uses the physical evidence projection, the `candidates`, `coverage`, and `evidence_bindings` contract, and allowlisted `evidence_check` diagnostics while preserving source-neutral semantics, Markdown as the sole source of truth, and zero SQLite runtime dependencies. Real-model semantics still require local acceptance with the selected model and representative inputs.
+> **Version: 0.2.32.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. Building on the existing UTF-8 evidence budget and metadata-mode pending-evidence policy, this release adds bounded `unknown_unit` Gate diagnostics for field path, type/length/digest and expected-set summaries, with at most three attempts and two corrections constrained by the same legal-ID inventory; it never logs the raw value or guesses an ID, and a persistently failed Gate does not advance the watermark or trigger cleanup. This preserves source-neutral semantics, Markdown as the sole source of truth, and zero SQLite runtime dependencies. 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
@@ -474,7 +474,7 @@ MIT; see [LICENSE](LICENSE).
 *Your memories, in files you own.*
 
 
-## General processing and read-only inspection (0.2.31)
+## General processing and read-only inspection (0.2.32)
 
 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.

{memleaf-0.2.31 → memleaf-0.2.32}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.31。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版统一 Core 与 Hermes Provider 的 UTF-8 证据留存预算：最多 64 条 source records、每条正文 32 KiB、正文总量 128 KiB，并保留有界 loss markers 与幂等规范化；同时将 metadata 模式下成功捕获的超限 pending 证据按相同有效策略消费。Gate 继续使用 physical evidence projection、`candidates`、`coverage`、`evidence_bindings` 和 allowlisted `evidence_check` 诊断，保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
+> **版本：0.2.32。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版在既有 UTF-8 证据留存预算和 metadata pending 消费策略上，为 Gate 的 `unknown_unit` 提供字段路径、类型/长度/摘要和期望集合摘要等受限诊断，并在同一合法 ID 清单约束下最多三次尝试、最多两次纠正；不记录原始值、不做 ID 猜测，持续失败不推进水位且不触发清理。保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -471,7 +471,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.31）
+## 通用处理与只读验收（0.2.32）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。

{memleaf-0.2.31 → memleaf-0.2.32}/docs/gate-evidence-boundary.md

@@ -62,6 +62,18 @@ Record a separate, allowlisted evidence-check identifier for the failing
 constraint. Diagnostics must not contain raw model responses, message text,
 credentials or arbitrary exception strings.
 
+An unknown unit reference must identify the exact response field, such as
+`coverage[2].unit_id` or `evidence_bindings[0].claims[1].unit_id`. Persist only
+the field path, value type/length/digest and expected-set count/digest. The
+invalid value and legal ID list do not belong in normal logs or failed state.
+
+A bounded retry receives the failed constraint, exact field path and the legal
+IDs from the same immutable model-visible inventory used by the validator.
+These IDs are a reference constraint, not a suggested semantic decision. The
+model must regenerate a consistent response; the host must not substitute a
+nearby ID, guess a source, or relax evidence authority. Prompt examples must not
+provide a literal placeholder that looks like a usable evidence reference.
+
 A failed Gate cannot advance the turn watermark or create a cleanup deadline.
 A successful no-change decision can advance the watermark and start the normal
 retention period. Incomplete physical observations remain deferred even if other
@@ -97,3 +109,9 @@ That adapter/capture limitation must be reported independently of Gate success.
 - Deterministic tests establish the protocol. Live synthetic tests establish
   behavior only for those samples. A synthetic success does not identify the
   cause of an earlier real-model failure; do not claim otherwise.
+
+A successful replay is evidence about that new run. If an earlier raw response
+was not retained, its precise invalid value cannot be recovered from an
+`unknown_unit` category alone. Verify recovery with controlled invalid coverage
+and binding references as well as ordinary live samples, and distinguish those
+results from reproduction of the original incident.

{memleaf-0.2.31 → memleaf-0.2.32}/docs/general-processing.md

@@ -1,4 +1,4 @@
-# General processing reliability contract — 0.2.30
+# General processing reliability contract — 0.2.32
 
 This is source-neutral processing, not a mail extractor. Dialogue, documents,
 calendars, issue trackers and terminal/tool observations use the same admission

{memleaf-0.2.31 → memleaf-0.2.32}/pyproject.toml

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

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.31"
+__version__ = "0.2.32"
 
 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.31 → memleaf-0.2.32}/src/memleaf/admission.py

@@ -242,7 +242,7 @@ def validate_bindings(value: Any, units: Iterable[EvidenceUnit],
                                evidence_check="binding_shape")
     result: dict[str, list[dict[str, Any]]] = {}
     allowed_roles = {"assertion", "source_excerpt", "user_confirmation"}
-    for row in value:
+    for binding_index, row in enumerate(value):
         if not isinstance(row, dict) or set(row) != {"candidate_id", "claims"}:
             raise ModelOutputError("invalid evidence binding", validation_detail="invalid_evidence",
                                    evidence_check="binding_shape")
@@ -255,7 +255,7 @@ def validate_bindings(value: Any, units: Iterable[EvidenceUnit],
             raise ModelOutputError("empty evidence claims", validation_detail="invalid_evidence",
                                    evidence_check="binding_shape")
         checked = []
-        for claim in claims:
+        for claim_index, claim in enumerate(claims):
             if not isinstance(claim, dict) or set(claim) not in (
                     {"unit_id", "start", "end", "quote", "role"}, {"unit_id", "quote", "role"}):
                 raise ModelOutputError("invalid evidence claim", validation_detail="invalid_evidence",
@@ -263,8 +263,13 @@ def validate_bindings(value: Any, units: Iterable[EvidenceUnit],
             claim = dict(claim)
             uid = claim["unit_id"]
             if not isinstance(uid, str) or uid not in by_unit:
-                raise ModelOutputError("unknown evidence unit", validation_detail="invalid_evidence",
-                                       evidence_check="unknown_unit")
+                error = ModelOutputError("unknown evidence unit", validation_detail="invalid_evidence",
+                                         evidence_check="unknown_unit")
+                raise error.with_evidence_context(
+                    path=f"evidence_bindings[{binding_index}].claims[{claim_index}].unit_id",
+                    actual=uid,
+                    expected_ids=tuple(by_unit),
+                )
             unit = by_unit[uid]
             quote = claim["quote"]
             if "start" not in claim:
@@ -356,20 +361,27 @@ _DEFERRED_COVERAGE_REASONS = frozenset({
 
 def parse_coverage(value: Any, units: Iterable[EvidenceUnit], candidates: Iterable[Mapping[str, Any]], *, require_complete: bool = True) -> dict[str, dict[str, Any]]:
     """Validate accounting without trusting the model's evidence identities."""
+    units = tuple(units)
+    expected_units = tuple(dict.fromkeys(u.unit_id for u in units))
     units = {u.unit_id: u for u in units}
     candidates = {c["candidate_id"]: c for c in candidates}
     if not isinstance(value, list):
         raise ModelOutputError("coverage must be a list", validation_detail="invalid_evidence",
                                evidence_check="coverage_shape")
     result = {}
-    for row in value:
+    for row_index, row in enumerate(value):
         if not isinstance(row, dict) or set(row) - {"unit_id", "decision", "candidate_ids", "reason"}:
             raise ModelOutputError("invalid coverage row", validation_detail="invalid_evidence",
                                    evidence_check="coverage_shape")
         uid = row.get("unit_id")
         if not isinstance(uid, str) or uid not in units:
-            raise ModelOutputError("invalid coverage unit", validation_detail="invalid_evidence",
-                                   evidence_check="unknown_unit")
+            error = ModelOutputError("invalid coverage unit", validation_detail="invalid_evidence",
+                                     evidence_check="unknown_unit")
+            raise error.with_evidence_context(
+                path=f"coverage[{row_index}].unit_id",
+                actual=uid,
+                expected_ids=expected_units,
+            )
         if uid in result:
             raise ModelOutputError("duplicate coverage unit", validation_detail="invalid_evidence",
                                    evidence_check="duplicate_coverage")
@@ -466,9 +478,10 @@ def evidence_prompt(units: Iterable[EvidenceUnit]) -> str:
         "candidates, coverage, and evidence_bindings. "
         "Coverage must contain exactly one row for EVERY supplied evidence unit. "
         "A response with coverage omitted or with coverage=[] is complete only when no units are supplied. "
-        "Each row is "
-        '{"unit_id":"supplied id","decision":"CANDIDATE","candidate_ids":["id"]} or '
-        '{"unit_id":"supplied id","decision":"NO_CHANGE or DEFERRED","reason":"reason"}. '
+        "For each row, copy unit_id character-for-character from the supplied evidence list. "
+        "Use decision=CANDIDATE with candidate_ids, or decision=NO_CHANGE/DEFERRED with reason. "
+        "The words in this schema description are labels only; never return a placeholder, event key, "
+        "call ID, or digest as unit_id. "
         'Allowed reasons: ' + ', '.join(sorted(COVERAGE_REASONS)) + '. '
         'Use NO_CHANGE only with reasons: ' + ', '.join(sorted(_NO_CHANGE_COVERAGE_REASONS)) + '. '
         'Use DEFERRED only with reasons: ' + ', '.join(sorted(_DEFERRED_COVERAGE_REASONS)) + '. '
@@ -489,9 +502,12 @@ def evidence_prompt(units: Iterable[EvidenceUnit]) -> str:
 
 
 SEMANTIC_BINDING_INSTRUCTIONS = """
-For every worth=true candidate, also return top-level evidence_bindings:
-[{"candidate_id":"existing candidate id","claims":[{"unit_id":"supplied id",
-"start":0,"end":10,"quote":"exact substring","role":"assertion"}]}].
+For every worth=true candidate, also return top-level evidence_bindings. Each
+binding must name a candidate_id copied from the candidates list and claims
+whose unit_id is copied character-for-character from the supplied evidence
+list. Do not return schema labels, placeholders, event keys, call IDs or
+digests as unit_id values. Each claim contains an exact quote and role, and
+may include start/end offsets.
 Offsets are relative to the supplied unit text. Roles: assertion (a current
 statement of fact or change), source_excerpt (actual quoted material, not a
 demonstration), user_confirmation (explicit adoption of a uniquely identified

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/hermes_provider/plugin.yaml

@@ -1,5 +1,5 @@
 name: memleaf
-version: 0.2.31
+version: 0.2.32
 description: "Hermes-native external MemoryProvider for local-first Markdown memory shared with the memleaf MCP server."
 hooks:
   - prefetch

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/model_execution.py

@@ -7,7 +7,7 @@ from .llm import MODEL_VALIDATION_REASONS, CallableBackend, ModelError, ModelUna
 from .models import utc_now
 from .prompts import COVERAGE_CORRECTION, DUPLICATE_TARGET_CORRECTION, GATE_TYPE_CORRECTION, JSON_CORRECTION, MIXED_FUTURE_USE_CORRECTION, MIXED_PROJECT_SCOPES_CORRECTION, RELATIVE_TIME_CORRECTION, SCOPE_GROUNDING_CORRECTION, SUMMARY_SCOPE_CORRECTION, SUMMARY_TARGET_CORRECTION, SUMMARY_TYPE_CORRECTION, TARGET_RELEVANCE_CORRECTION, UPDATE_TARGET_TYPE_CORRECTION
 from .validation import MODEL_VALIDATION_DETAILS, ModelOutputError
-from .process_common import _DIAGNOSTIC_FILENAME, _DIAGNOSTIC_MAX_BYTES, _failure_metadata, _model_output_statistics, _safe_evidence_check
+from .process_common import _DIAGNOSTIC_FILENAME, _DIAGNOSTIC_MAX_BYTES, _failure_metadata, _model_output_statistics, _safe_evidence_check, _safe_evidence_diagnostics
 
 
 class ModelExecutor:
@@ -114,7 +114,8 @@ class ModelExecutor:
         if stage == "gate" and hint == "target_not_relevant":
             return TARGET_RELEVANCE_CORRECTION
         if stage == "gate" and hint == "invalid_evidence":
-            return COVERAGE_CORRECTION
+            context = ModelExecutor._evidence_correction_context(error)
+            return COVERAGE_CORRECTION if context is None else COVERAGE_CORRECTION + "\n" + context
         if stage == "summarize" and hint == "scope_drift":
             return SUMMARY_SCOPE_CORRECTION
         if hint == "relative_time":
@@ -128,6 +129,39 @@ class ModelExecutor:
         return None
 
 
+    @staticmethod
+    def _evidence_correction_context(error: BaseException) -> Optional[str]:
+        """Build a bounded Gate repair hint from validator-owned context only."""
+
+        if getattr(error, "evidence_check", None) != "unknown_unit":
+            return None
+        diagnostics = _safe_evidence_diagnostics(error)
+        path = diagnostics.get("evidence_path")
+        expected = getattr(error, "evidence_expected_ids", ())
+        if not isinstance(path, str) or not isinstance(expected, tuple) or not all(
+            isinstance(item, str) and item for item in expected
+        ):
+            return None
+        expected_json = json.dumps(list(expected), ensure_ascii=False, separators=(",", ":"))
+        actual_parts = []
+        for key, label in (("evidence_actual_type", "type"), ("evidence_actual_length", "length"),
+                           ("evidence_actual_sha256", "sha256")):
+            if key in diagnostics:
+                actual_parts.append(f"{label}={diagnostics[key]}")
+        descriptor = ", ".join(actual_parts) or "no safe value descriptor"
+        legal = (
+            f"the complete legal unit_id set is exactly {expected_json}. "
+            if expected else "there are no legal unit_id values in this call. "
+        )
+        return (
+            "Evidence reference diagnostic (structural only): evidence_check=unknown_unit; "
+            "the invalid unit_id was at "
+            f"{path}. Safe descriptor: {descriptor}. For this call, {legal}"
+            "Copy one legal unit_id character-for-character from that set when one exists; "
+            "do not use the invalid value, a placeholder, event_key, call ID, digest, or a guessed mapping."
+        )
+
+
     def _diagnostic_enabled(self) -> bool:
         try:
             config = self.service.vault.config()
@@ -187,6 +221,7 @@ class ModelExecutor:
         }
         if evidence_check is not None:
             entry["evidence_check"] = evidence_check
+        entry.update(_safe_evidence_diagnostics(error) if error is not None else {})
         response_diagnostics = getattr(error, "response_diagnostics", None) if error is not None else None
         if isinstance(response_diagnostics, Mapping):
             allowed_diagnostics = {

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/process_common.py

@@ -16,7 +16,7 @@ from .llm import MODEL_ERROR_CODES, MODEL_VALIDATION_REASONS, ModelUnavailable
 from .locking import read_json
 from .models import Memory, utc_now
 from .retrieval import candidate_matches_query, normalize_term
-from .validation import MODEL_EVIDENCE_CHECKS, MODEL_VALIDATION_DETAILS, ModelOutputError, parse_strict_json, normalize_relative_calendar_text
+from .validation import MODEL_EVIDENCE_CHECKS, MODEL_VALIDATION_DETAILS, ModelOutputError, parse_strict_json, normalize_relative_calendar_text, safe_evidence_context
 
 _PROCESSING_LEASE_SECONDS = 3600
 
@@ -298,6 +298,12 @@ def _safe_evidence_check(error: BaseException) -> Optional[str]:
     return value if isinstance(value, str) and value in MODEL_EVIDENCE_CHECKS else None
 
 
+def _safe_evidence_diagnostics(error: BaseException) -> dict[str, Any]:
+    """Return allowlisted structural evidence details for local diagnostics."""
+
+    return safe_evidence_context(error)
+
+
 def _json_top_level_type(value: Any) -> str:
     if isinstance(value, Mapping):
         return "object"

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/process_journal.py

@@ -15,7 +15,7 @@ from .locking import atomic_write_json, atomic_write_text
 from .turn_plan import turn_identity_key
 from .redaction import redact_text
 from .vault import safe_component
-from .process_common import ProcessingError, _FAILED_STATUS, _LEGACY_PROCESSING_GRACE_SECONDS, _MAX_SESSION_LINEAGE_DEPTH, _PROCESSING_LEASE_SECONDS, _PROCESSING_STATUS, _Snapshot, _as_int, _failure_metadata, _now_value, _parse_time, _read_processed, _safe_evidence_check, _safe_scope_background, _session_key
+from .process_common import ProcessingError, _FAILED_STATUS, _LEGACY_PROCESSING_GRACE_SECONDS, _MAX_SESSION_LINEAGE_DEPTH, _PROCESSING_LEASE_SECONDS, _PROCESSING_STATUS, _Snapshot, _as_int, _failure_metadata, _now_value, _parse_time, _read_processed, _safe_evidence_check, _safe_evidence_diagnostics, _safe_scope_background, _session_key
 
 
 class ProcessJournal:
@@ -371,6 +371,7 @@ class ProcessJournal:
                         failed_marker["validation_detail"] = validation_detail
                     if evidence_check is not None:
                         failed_marker["evidence_check"] = evidence_check
+                    failed_marker.update(_safe_evidence_diagnostics(error))
                     if attempt_count is not None:
                         failed_marker["attempt_count"] = attempt_count
                     state["processing"] = failed_marker

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/prompts.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 
 GATE_SYSTEM = """You are memleaf's strict, source-neutral memory gate. Return exactly one strict JSON object with the top-level fields candidates, coverage, and evidence_bindings.
-When physical evidence units are supplied, coverage must contain exactly one row for every supplied unit. An empty coverage list is complete only when no physical evidence units are supplied. Never omit a supplied physical evidence unit from coverage. A binding is {"candidate_id":"id","claims":[{"unit_id":"supplied id","start":0,"end":5,"quote":"exact substring","role":"assertion"}]}. start/end are Python Unicode offsets relative to unit.text; both may be omitted only when the exact quote occurs once. role is assertion, source_excerpt, or user_confirmation. When no physical evidence is supplied, return {"candidates":[],"coverage":[],"evidence_bindings":[]}.
+When physical evidence units are supplied, coverage must contain exactly one row for every supplied unit. An empty coverage list is complete only when no physical evidence units are supplied. Never omit a supplied physical evidence unit from coverage. For bindings, copy candidate_id from the returned candidates and copy unit_id character-for-character from the supplied Evidence units list; schema labels and placeholders are not valid values. start/end are Python Unicode offsets relative to unit.text; both may be omitted only when the exact quote occurs once. role is assertion, source_excerpt, or user_confirmation. When no physical evidence is supplied, return {"candidates":[],"coverage":[],"evidence_bindings":[]}.
 
 Physical source_role is supplied by the host and is immutable. Current user assertions and matched current-turn external observations may support new memory. Assistant synthesis, retrieved memleaf/native memory, questions, hypothetical/example text, and unsupported inference do not independently authorize a write. Exact quotation proves provenance only; semantic entailment, ownership, polarity, uncertainty, conditions and future value are your responsibility.
 

{memleaf-0.2.31 → memleaf-0.2.32}/src/memleaf/validation.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 from datetime import date, datetime, timedelta, timezone
@@ -43,12 +44,50 @@ class ModelOutputError(ValueError):
             if isinstance(evidence_check, str) and evidence_check in MODEL_EVIDENCE_CHECKS
             else None
         )
+        # Evidence diagnostics are attached by the local Gate validator. They
+        # are intentionally kept separate from ``str(error)`` so callers can
+        # safely expose only the allowlisted structural fields below.
+        self.evidence_path: str | None = None
+        self.evidence_actual_type: str | None = None
+        self.evidence_actual_length: int | None = None
+        self.evidence_actual_sha256: str | None = None
+        self.evidence_expected_ids: tuple[str, ...] = ()
+        self.evidence_expected_count: int | None = None
+        self.evidence_expected_sha256: str | None = None
 
     def with_detail(self, detail: str | None) -> "ModelOutputError":
         if isinstance(detail, str) and detail in MODEL_VALIDATION_DETAILS:
             self.validation_detail = detail
         return self
 
+    def with_evidence_context(
+        self,
+        *,
+        path: str,
+        actual: Any,
+        expected_ids: Iterable[Any],
+    ) -> "ModelOutputError":
+        """Attach bounded evidence-reference diagnostics without raw values.
+
+        Expected IDs are retained on the exception for the transient retry
+        prompt. Persistent diagnostics must use ``safe_evidence_context``
+        below, which deliberately omits both the IDs and the invalid value.
+        """
+
+        if not isinstance(path, str) or not _EVIDENCE_PATH_RE.fullmatch(path):
+            return self
+        expected = tuple(dict.fromkeys(
+            item for item in expected_ids if isinstance(item, str) and item
+        ))
+        self.evidence_path = path
+        self.evidence_actual_type, self.evidence_actual_length, self.evidence_actual_sha256 = (
+            _evidence_value_descriptor(actual)
+        )
+        self.evidence_expected_ids = expected
+        self.evidence_expected_count = len(expected)
+        self.evidence_expected_sha256 = _evidence_ids_digest(expected)
+        return self
+
 
 MEMORY_TYPES = frozenset(("preference", "fact", "project", "todo", "event", "identity", "other"))
 SCOPE_SOURCES = frozenset(("model", "user", "session_context", "insufficient_context"))
@@ -101,6 +140,88 @@ MODEL_EVIDENCE_CHECKS = frozenset((
     "coverage_binding_conflict",
     "candidate_evidence",
 ))
+
+_EVIDENCE_PATH_RE = re.compile(
+    r"(?:coverage\[\d+\]\.unit_id|evidence_bindings\[\d+\]\.claims\[\d+\]\.unit_id)"
+)
+_EVIDENCE_VALUE_TYPES = frozenset(("null", "boolean", "number", "string", "array", "object", "other"))
+_EVIDENCE_DIAGNOSTIC_MAX_LENGTH = 1_000_000
+
+
+def _evidence_value_descriptor(value: Any) -> tuple[str, int | None, str]:
+    """Return a safe type/length/digest descriptor for a model JSON value."""
+
+    if value is None:
+        value_type = "null"
+        length = None
+    elif isinstance(value, bool):
+        value_type = "boolean"
+        length = None
+    elif isinstance(value, (int, float)):
+        value_type = "number"
+        length = None
+    elif isinstance(value, str):
+        value_type = "string"
+        length = min(len(value), _EVIDENCE_DIAGNOSTIC_MAX_LENGTH)
+    elif isinstance(value, list):
+        value_type = "array"
+        length = min(len(value), _EVIDENCE_DIAGNOSTIC_MAX_LENGTH)
+    elif isinstance(value, dict):
+        value_type = "object"
+        length = min(len(value), _EVIDENCE_DIAGNOSTIC_MAX_LENGTH)
+    else:
+        value_type = "other"
+        length = None
+    try:
+        encoded = json.dumps(value, ensure_ascii=False, allow_nan=False,
+                             sort_keys=True, separators=(",", ":")).encode("utf-8")
+    except (TypeError, ValueError):
+        encoded = value_type.encode("ascii")
+    return value_type, length, hashlib.sha256(encoded).hexdigest()
+
+
+def _evidence_ids_digest(ids: Iterable[str]) -> str:
+    encoded = json.dumps(list(ids), ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def safe_evidence_context(error: BaseException) -> dict[str, Any]:
+    """Return only allowlisted structural evidence diagnostics for persistence."""
+
+    path = getattr(error, "evidence_path", None)
+    if not isinstance(path, str) or not _EVIDENCE_PATH_RE.fullmatch(path):
+        path = None
+    value_type = getattr(error, "evidence_actual_type", None)
+    if not isinstance(value_type, str) or value_type not in _EVIDENCE_VALUE_TYPES:
+        value_type = None
+    length = getattr(error, "evidence_actual_length", None)
+    if isinstance(length, bool) or not isinstance(length, int) or not 0 <= length <= _EVIDENCE_DIAGNOSTIC_MAX_LENGTH:
+        length = None
+    digest = getattr(error, "evidence_actual_sha256", None)
+    if not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest):
+        digest = None
+    expected_count = getattr(error, "evidence_expected_count", None)
+    if isinstance(expected_count, bool) or not isinstance(expected_count, int) or not 0 <= expected_count <= _EVIDENCE_DIAGNOSTIC_MAX_LENGTH:
+        expected_count = None
+    expected_digest = getattr(error, "evidence_expected_sha256", None)
+    if not isinstance(expected_digest, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_digest):
+        expected_digest = None
+    result: dict[str, Any] = {}
+    if path is not None:
+        result["evidence_path"] = path
+    if value_type is not None:
+        result["evidence_actual_type"] = value_type
+    if length is not None:
+        result["evidence_actual_length"] = length
+    if digest is not None:
+        result["evidence_actual_sha256"] = digest
+    if expected_count is not None:
+        result["evidence_expected_count"] = expected_count
+    if expected_digest is not None:
+        result["evidence_expected_sha256"] = expected_digest
+    return result
+
+
 _SCOPE_NAME = re.compile(r"^[^\s/\\:\x00\r\n]+$")
 _RELATIVE_DATE_TOKEN = (
     r"(?:"
@@ -1372,6 +1493,7 @@ __all__ = [
     "MODEL_VALIDATION_REASONS",
     "ModelOutputError",
     "NO_CHANGE_DECISION",
+    "safe_evidence_context",
     "SCOPE_SOURCES",
     "TODO_STATUSES",
     "parse_gate",

{memleaf-0.2.31 → memleaf-0.2.32/src/memleaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.31
+Version: 0.2.32
 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.31。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版统一 Core 与 Hermes Provider 的 UTF-8 证据留存预算：最多 64 条 source records、每条正文 32 KiB、正文总量 128 KiB，并保留有界 loss markers 与幂等规范化；同时将 metadata 模式下成功捕获的超限 pending 证据按相同有效策略消费。Gate 继续使用 physical evidence projection、`candidates`、`coverage`、`evidence_bindings` 和 allowlisted `evidence_check` 诊断，保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
+> **版本：0.2.32。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版在既有 UTF-8 证据留存预算和 metadata pending 消费策略上，为 Gate 的 `unknown_unit` 提供字段路径、类型/长度/摘要和期望集合摘要等受限诊断，并在同一合法 ID 清单约束下最多三次尝试、最多两次纠正；不记录原始值、不做 ID 猜测，持续失败不推进水位且不触发清理。保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -490,7 +490,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.31）
+## 通用处理与只读验收（0.2.32）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。