memleaf 0.2.48__tar.gz → 0.2.49__tar.gz

{memleaf-0.2.48 → memleaf-0.2.49}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.49 — 2026-09-13
+
+- Restore candidate-local deferral to the B3 single-pass path. v0.2.26 established that an invalid proposal receives bounded model correction and then explicit candidate-local deferral while "valid siblings proceed", and v0.2.34 required that "candidate-local deferral and idempotent partial retries" be preserved so unresolved ownership, target, evidence or timing never fabricates a write. The B3 planner had lost that property: the first proposal Core rejected raised out of the parser and discarded every other verdict in the turn, so one model slip cost the whole turn even when six other candidates were sound. A proposal that Core can attribute to a single candidate is now deferred with a B3 defer reason and the rest of the turn still commits. Nothing is written for a deferred candidate, no extra model call is made, and the turn stays retryable with its already-settled units intact.
+- Keep the deferral boundary narrow and explicit. Only details that describe the candidate itself are converted: scope authorisation and update-target problems map to `scope_ambiguous` and `target_ambiguous`, while a malformed proposal (todo fields, ungrounded or malformed dates, type, source shape) maps to `maintenance_uncertain` and missing admitted evidence maps to `evidence_insufficient`. Every other failure — transport, truncation, envelope shape, evidence coverage, binding scope, and any detail Core does not recognise — still fails the whole turn closed, so a systemic fault cannot hide behind a deferral.
+- Make the deferral visible rather than silent. Each one is counted as `b3_candidate_deferred_count` on the turn, the cause is recorded against the candidate, and the deferred work continues to surface through `deferred_candidates`, `retryable_deferred_turns` and `coverage_status: partial` in the read-only processing status. The persisted cause is restricted to a bounded identifier so no model text can reach state files.
+- Keep the deferral from being mistaken for a collision. Same-target reconciliation groups items that reach a terminal disposition for one memory, and a deferred candidate reaches none: it writes nothing, carries no update target, and cannot conflict with an admitted update to the same memory. Only the candidates that actually reach UPDATE or NO_CHANGE are grouped now, so a turn that updates one memory and defers another does not spend its second request reconciling a candidate that was never admitted.
+
+Verification for this release repeated the same real-model replay used for 0.2.48 and added focused synthetic tests: 90 tests pass with no model call, covering the sibling-commits case, every deferrable detail and the reason it maps to, deferral being driven by an explicit allowlist, the optional argument for direct parser callers, a deferred member not being grouped as a same-target collision, and the turn-level failures that must still abort. Three further preview runs of the previously failing production session completed with `execution_status: ok` and `coverage_status: complete`. A deferral is a visible degradation rather than a success: the candidate is retried, not written, and a prompt or configuration fault that made every proposal invalid would now show up as a fully deferred turn rather than as a hard failure.
+
 ## 0.2.48 — 2026-09-13
 
 - Restore same-target reconciliation in the B3 single-pass path. A real turn was discarded with `B3 target referenced more than once` whenever the model admitted two changes for one existing memory. One memory can only receive one terminal disposition per turn, because the writer archives the previous version and overwrites the same file, so the colliding items are now reconciled with one bounded call into a single current state and an unresolvable group is deferred as `target_ambiguous` instead of guessed. This is the capability the legacy staged path already had; it is not a new retry class, and the compact contract now tells the model to merge such changes into one UPDATE in the first place. The call is charged against the same two-request turn budget as the primary extraction and its structural repair, so a collision can never lengthen a turn: when a repair has already spent the budget, the group defers and every other item still commits. The strict "a target may be used once" rejection remains in the parser for direct callers.

{memleaf-0.2.48/src/memleaf.egg-info → memleaf-0.2.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.48
+Version: 0.2.49
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.48。**
+> **版本：0.2.49。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.48 → memleaf-0.2.49}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.48.**
+> **Version: 0.2.49.**
 > Automatic extraction now uses only the current turn's visible user input and final assistant reply. Raw tool output, attachments, web/file/terminal payloads and legacy tool-evidence bodies are not new source evidence; existing or retrieved memory remains comparison context rather than source authority. Background processing is persisted as a local job and can be checked through the read-only `process_status` MCP tool; failed work remains retryable and fail closed. The release also tightens source/date grounding, target reconciliation, duplicate/no-op handling and semantic review before writes. Markdown remains the sole source of truth with no SQLite runtime dependency. Acceptance covers deterministic regression suites and synthetic inputs; it does not claim real-mail or customer-business acceptance.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 

{memleaf-0.2.48 → memleaf-0.2.49}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.48。**
+> **版本：0.2.49。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.48 → memleaf-0.2.49}/pyproject.toml

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

{memleaf-0.2.48 → memleaf-0.2.49}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.48"
+__version__ = "0.2.49"
 
 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.48 → memleaf-0.2.49}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.48 → memleaf-0.2.49}/src/memleaf/single_pass_plan.py

@@ -45,6 +45,29 @@ _DEFER_REASONS = frozenset({
     "lookup_incomplete",
     "maintenance_uncertain",
 })
+# A rejected proposal is a candidate-local problem, not a turn-local one.
+# v0.2.26 established that "invalid proposals receive bounded model correction,
+# then explicit candidate-local deferral; valid siblings proceed", and v0.2.34
+# required that candidate-local deferral and idempotent partial retries be
+# preserved.  Only details that describe the candidate itself are listed here:
+# anything unrecognised, and every transport or invariant failure, still fails
+# the whole turn closed.
+_B3_DEFERRABLE_DETAILS = {
+    "scope_not_grounded": "scope_ambiguous",
+    "scope_drift": "scope_ambiguous",
+    "invalid_scope": "scope_ambiguous",
+    "invalid_scope_source": "scope_ambiguous",
+    "invalid_update_target": "target_ambiguous",
+    "duplicate_update_target": "target_ambiguous",
+    "invalid_due_date": "maintenance_uncertain",
+    "due_date_not_grounded": "maintenance_uncertain",
+    "relative_time": "maintenance_uncertain",
+    "todo_fields": "maintenance_uncertain",
+    "invalid_type": "maintenance_uncertain",
+    "source_shape": "maintenance_uncertain",
+    "invalid_evidence": "evidence_insufficient",
+}
+_DETAIL_TEXT_RE = re.compile(r"^[a-z_]{1,48}$")
 _MEMORY_FIELDS = frozenset({
     "title", "body", "tags", "aliases", "keywords", "status", "completed_at", "due_date",
     "shadow_native_ids",
@@ -409,6 +432,7 @@ def parse_single_pass_output(
     validate_memory: MemoryValidator,
     target_rows: list[dict[str, Any]] | None = None,
     normalizations: list[str] | None = None,
+    deferrals: list[dict[str, Any]] | None = None,
 ) -> dict[str, Any]:
     if not callable(validate_memory):
         raise TypeError("validate_memory must be callable")
@@ -717,30 +741,54 @@ def parse_single_pass_output(
     for item, target_record in prepared:
         candidate_id = item["candidate_id"]
         decision = item["decision"]
+        evidence = [dict(claim) for claim in bindings[candidate_id]]
         normalized: dict[str, Any] = {
             "candidate_id": candidate_id,
             "decision": decision,
-            "evidence": [dict(claim) for claim in bindings[candidate_id]],
+            "evidence": evidence,
         }
-        if decision == "CREATE":
-            validated = validate_memory(
-                candidate_id, decision, None, None, item["memory"], normalized["evidence"], item,
-            )
-            normalized.update({
-                "type": item["type"], "scopes": list(item["scopes"]), "memory": dict(validated),
-            })
-        elif decision == "UPDATE":
-            target_id = item["target_memory_id"]
-            validated = validate_memory(
-                candidate_id, decision, target_id, target_record,
-                item["memory"], normalized["evidence"], item,
-            )
-            normalized["target_memory_id"] = target_id
-            normalized["memory"] = dict(validated)
-        elif decision == "NO_CHANGE":
-            normalized["target_memory_id"] = item["target_memory_id"]
-        else:
-            normalized["reason"] = item["reason"]
+        try:
+            if decision == "CREATE":
+                validated = validate_memory(
+                    candidate_id, decision, None, None, item["memory"], evidence, item,
+                )
+                normalized.update({
+                    "type": item["type"], "scopes": list(item["scopes"]), "memory": dict(validated),
+                })
+            elif decision == "UPDATE":
+                target_id = item["target_memory_id"]
+                validated = validate_memory(
+                    candidate_id, decision, target_id, target_record,
+                    item["memory"], evidence, item,
+                )
+                normalized["target_memory_id"] = target_id
+                normalized["memory"] = dict(validated)
+            elif decision == "NO_CHANGE":
+                normalized["target_memory_id"] = item["target_memory_id"]
+            else:
+                normalized["reason"] = item["reason"]
+        except ModelOutputError as error:
+            detail = getattr(error, "validation_detail", None)
+            reason = _B3_DEFERRABLE_DETAILS.get(detail) if isinstance(detail, str) else None
+            if reason is None:
+                raise
+            # The proposal is unsafe to write, but its siblings are unaffected.
+            # Defer this one candidate so the turn keeps every verdict it can
+            # justify, and record the cause instead of failing silently.
+            normalized = {
+                "candidate_id": candidate_id,
+                "decision": "DEFERRED",
+                "reason": reason,
+                "evidence": evidence,
+            }
+            if deferrals is not None:
+                deferrals.append({
+                    "candidate_id": candidate_id,
+                    "reason": reason,
+                    "detail": (
+                        detail if _DETAIL_TEXT_RE.fullmatch(detail) else "unrecognised_detail"
+                    ),
+                })
         normalized_items.append(normalized)
     return {"protocol_version": PROTOCOL_VERSION, "items": normalized_items, "no_memory": normalized_no_memory}
 
@@ -1060,10 +1108,12 @@ def run_single_pass_stage(
     primary_system = "" if inline_system else SINGLE_PASS_SYSTEM
     target_rows: list[dict[str, Any]] = []
     normalizations: list[str] = []
+    deferrals: list[dict[str, Any]] = []
 
     def parse(raw: str) -> dict[str, Any]:
         target_rows.clear()
         normalizations.clear()
+        deferrals.clear()
         return parse_single_pass_output(
             raw,
             evidence_units=source_units,
@@ -1072,6 +1122,7 @@ def run_single_pass_stage(
             validate_memory=validate_memory,
             target_rows=target_rows,
             normalizations=normalizations,
+            deferrals=deferrals,
         )
 
     def finalize(parsed: dict[str, Any]) -> dict[str, Any]:
@@ -1084,12 +1135,6 @@ def run_single_pass_stage(
         and an unresolvable group is deferred instead of guessed.
         """
 
-        grouped: dict[str, list[str]] = {}
-        for row in target_rows:
-            grouped.setdefault(str(row["target"]), []).append(str(row["candidate_id"]))
-        collisions = {key: ids for key, ids in grouped.items() if len(ids) > 1}
-        if not collisions:
-            return parsed
         items = parsed.get("items")
         if not isinstance(items, list) or not items:
             return parsed
@@ -1098,6 +1143,22 @@ def run_single_pass_stage(
             for index, row in enumerate(items)
             if isinstance(row, Mapping)
         }
+        terminal_ids = {
+            str(row.get("candidate_id"))
+            for row in items
+            if isinstance(row, Mapping) and row.get("decision") in {"UPDATE", "NO_CHANGE"}
+        }
+        grouped: dict[str, list[str]] = {}
+        for row in target_rows:
+            candidate_id = str(row["candidate_id"])
+            if candidate_id not in terminal_ids:
+                # A candidate Core deferred writes nothing, so it cannot
+                # collide with a terminal disposition for the same memory.
+                continue
+            grouped.setdefault(str(row["target"]), []).append(candidate_id)
+        collisions = {key: ids for key, ids in grouped.items() if len(ids) > 1}
+        if not collisions:
+            return parsed
 
         def union_evidence(members: Sequence[Mapping[str, Any]]) -> list[Any]:
             merged: list[Any] = []
@@ -1273,6 +1334,8 @@ def run_single_pass_stage(
             event(repair_context, "parse_accepted_count")
             if normalizations:
                 event(repair_context, "b3_normalization_count", len(normalizations))
+            if deferrals:
+                event(repair_context, "b3_candidate_deferred_count", len(deferrals))
         writer = getattr(model_executor, "_write_model_diagnostic", None)
         if callable(writer):
             try:
@@ -1289,6 +1352,8 @@ def run_single_pass_stage(
         event(primary_context, "parse_accepted_count")
         if normalizations:
             event(primary_context, "b3_normalization_count", len(normalizations))
+        if deferrals:
+            event(primary_context, "b3_candidate_deferred_count", len(deferrals))
     writer = getattr(model_executor, "_write_model_diagnostic", None)
     if callable(writer):
         try:

{memleaf-0.2.48 → memleaf-0.2.49/src/memleaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.48
+Version: 0.2.49
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.48。**
+> **版本：0.2.49。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。