memleaf 0.2.42__tar.gz → 0.2.44__tar.gz

{memleaf-0.2.42 → memleaf-0.2.44}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.44 — 2026-09-12
+
+- Correct the extraction latency policy: ten seconds is an advisory performance target, not a cancellation or commit deadline. Remove the fixed six-second primary cap and eight-second shared window; single-pass HTTP requests now honor `llm.request_timeout`, including the one bounded format repair.
+- Accept valid, Core-checked results after the target and recover frozen background plans without expiring them by old wall-clock timestamps. Keep durable request counts, damaged-state handling, revision/ownership validation and normal transport errors intact.
+- Add structural per-turn extraction timing to synchronous results and background job result/error summaries. Track planning/commit time, slow attempts and failed attempts separately; a fast failure is not counted as successful target achievement. No prompt, response, credential or memory body is added to these metrics.
+- Keep tests local-only and leave the hosted build/smoke CI policy unchanged. Real-provider latency and quality acceptance remain separate; removing premature cancellation is not a measured ten-second performance claim.
+
+## 0.2.43 — 2026-09-12
+
+- Keep regression tests, live-acceptance helpers, and implementation/release plans in local checkouts rather than the Git tree or source distribution.
+- Narrow hosted CI to package build and installed-command smoke checks while retaining the existing release metadata checks and GitHub/PyPI publication workflow.
+
 ## 0.2.42 — 2026-09-12
 
 - Rework ordinary automatic extraction around the unified `b3-single-pass-v1` planner. The current visible user/assistant turn is the only new-fact evidence; existing local/native memories remain comparison context. One structured model stage decides CREATE / UPDATE / NO_CHANGE / DEFERRED, with deterministic Core validation and at most one bounded format/structure repair.

{memleaf-0.2.42 → memleaf-0.2.44}/MANIFEST.in

@@ -4,9 +4,8 @@ include install.sh
 include install.ps1
 include README.md
 include README.en.md
-include RELEASE_CHECKLIST.md
-include IMPLEMENTATION_PLAN.md
-recursive-include tests *.py
 recursive-include examples *.md *.ndjson *.py
+recursive-exclude examples *_acceptance.py
+prune tests
 
 include docs/*.md

{memleaf-0.2.42/src/memleaf.egg-info → memleaf-0.2.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.42
+Version: 0.2.44
 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.42。**
+> **版本：0.2.44。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -85,6 +85,8 @@ Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Sco
 
 ## 记忆提炼规则
 
+**10 秒是自动提炼的性能目标，不是失败阈值。** HTTP 请求遵循 `llm.request_timeout`（默认 120 秒）；正常返回且通过 Core 校验的结果不会仅因超过 10 秒而丢弃。模型单次请求、有限修复和逐轮提交保留，耗时与是否完成分别统计。详见 [提炼耗时与超时](docs/extraction-latency.md)。
+
 memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
 
 - `CREATE`：没有相关现存记忆，创建一条原子、可独立理解的记忆；
@@ -451,17 +453,9 @@ history:
 - 选择 API/云端模型后，模型处理输入会离开本机并发送给该提供方；
 - `context()` 或无宿主绑定的客户端只能获得单页边界，不能宣称具备跨轮硬预算。
 
-## 开发与验证
-
-要求 Python 3.11+。本地运行测试：
-
-```bash
-PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
-python3.11 -m compileall -q src tests examples
-git diff --check
-```
+## 开发与构建
 
-GitHub Actions 覆盖 Linux 与 Windows 的 Python 3.11、3.12、3.13 测试，并验证 wheel/source distribution 构建、源码包测试和 Windows PowerShell 安装器语法。构建发行包需要 `build`：
+要求 Python 3.11+。GitHub Actions 在 Python 3.12 上构建 wheel 和 source distribution，并对安装后的包、命令入口和版本信息做冒烟检查。构建发行包需要 `build`：
 
 ```bash
 python -m pip install build

{memleaf-0.2.42 → memleaf-0.2.44}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.42.**
+> **Version: 0.2.44.**
 > 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.
 
@@ -64,6 +64,8 @@ Hermes uses a native MemoryProvider for lifecycle handling and obtains the Scope
 
 ## Memory admission and maintenance
 
+**Ten seconds is an extraction performance target, not a failure deadline.** HTTP requests honor `llm.request_timeout` (120 seconds by default). A valid, Core-checked response is not discarded just because processing exceeds ten seconds. Single-pass planning, bounded repair and per-turn commits remain; completion and latency are measured separately. See [extraction latency and timeouts](docs/extraction-latency.md).
+
 memleaf does not save every sentence. When a complete visible user + assistant turn is processed, the model first evaluates whether it has concrete future reuse value:
 
 - `CREATE`: no related active memory exists, so create one atomic, self-contained memory;
@@ -434,17 +436,9 @@ Directories are normally created with mode `0700`, and files are stored as plain
 - If an API or cloud model is selected, model-processing input leaves the machine and is sent to that provider.
 - `context()` and clients without a host-bound retrieval turn only have per-page limits; they cannot claim cross-turn hard budgets.
 
-## Development and verification
-
-Python 3.11+ is required. Run locally:
-
-```bash
-PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
-python3.11 -m compileall -q src tests examples
-git diff --check
-```
+## Development and builds
 
-GitHub Actions covers Python 3.11, 3.12, and 3.13 on Linux and Windows, plus wheel/source-distribution builds, source-archive tests, and PowerShell installer syntax validation. Build packages with:
+Python 3.11+ is required. GitHub Actions builds the wheel and source distribution on Python 3.12, then smoke-checks the installed package, CLI entry points, and version commands. Build packages with:
 
 ```bash
 python -m pip install build

{memleaf-0.2.42 → memleaf-0.2.44}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.42。**
+> **版本：0.2.44。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -66,6 +66,8 @@ Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Sco
 
 ## 记忆提炼规则
 
+**10 秒是自动提炼的性能目标，不是失败阈值。** HTTP 请求遵循 `llm.request_timeout`（默认 120 秒）；正常返回且通过 Core 校验的结果不会仅因超过 10 秒而丢弃。模型单次请求、有限修复和逐轮提交保留，耗时与是否完成分别统计。详见 [提炼耗时与超时](docs/extraction-latency.md)。
+
 memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
 
 - `CREATE`：没有相关现存记忆，创建一条原子、可独立理解的记忆；
@@ -432,17 +434,9 @@ history:
 - 选择 API/云端模型后，模型处理输入会离开本机并发送给该提供方；
 - `context()` 或无宿主绑定的客户端只能获得单页边界，不能宣称具备跨轮硬预算。
 
-## 开发与验证
-
-要求 Python 3.11+。本地运行测试：
-
-```bash
-PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
-python3.11 -m compileall -q src tests examples
-git diff --check
-```
+## 开发与构建
 
-GitHub Actions 覆盖 Linux 与 Windows 的 Python 3.11、3.12、3.13 测试，并验证 wheel/source distribution 构建、源码包测试和 Windows PowerShell 安装器语法。构建发行包需要 `build`：
+要求 Python 3.11+。GitHub Actions 在 Python 3.12 上构建 wheel 和 source distribution，并对安装后的包、命令入口和版本信息做冒烟检查。构建发行包需要 `build`：
 
 ```bash
 python -m pip install build

memleaf-0.2.44/docs/extraction-latency.md

@@ -0,0 +1,50 @@
+# 提炼耗时与请求超时
+
+## 性能目标与失败条件分开
+
+日常自动提炼以 10 秒内完成为性能目标，但到第 10 秒不会主动报失败，也不会丢弃已正常返回并通过 Core 校验的结果。超过目标说明本次处理偏慢，不说明记忆无效或没有需要保存的信息。
+
+v0.2.42 / v0.2.43 的固定 6 秒首请求、8 秒准备加模型窗口、10 秒提交前拒绝属于错误的目标实现，当前修正移除了这些时间闸门。修正本身不代表真实模型的 P50/P95 已达标。
+
+HTTP 请求使用已有配置：
+
+```yaml
+llm:
+  request_timeout: 120
+```
+
+这个参数仍按现有规则校验（1～240 秒，可用小数），并传到 HTTP transport。single-pass 不再静默把它缩短为 6 秒。第二次结构修复请求使用相同的配置，不再只分到原来 8 秒窗口的剩余时间。请求超时是 transport 的等待限制，不是整个后台任务的端到端完成保证；host/Python callback 仍由其宿主负责请求超时与取消。
+
+真正的请求超时、网络故障、无效模型输出、目标版本冲突、写入失败仍然是失败或未完成，不能伪装为 `NO_CHANGE`。相应 inbox、journal 和恢复锚点保留，是否提交仍由 Core 校验决定。
+
+## 保留的调用与提交约束
+
+普通 B3 自动提炼仍以一次结构化模型调用为正常路径，格式/结构修复最多一次。固定安全路由保留实际 outbound 请求计数和持久化预占，不增加隐藏 host-to-API fallback。并未恢复 Gate → Summary → Review 多阶段主路径。
+
+每轮仍先读取持久状态、规划、校验、提交，再处理下一轮；一轮超过目标不会占用下一轮的“时间许可”。compaction 仍不在普通提炼的关键路径上。
+
+旧 `extraction_request_budget.json` 中的 `started_at_epoch` 可以兼容读取，但不再作为请求或提交的过期时间。已消耗的 `requests` 不清零，损坏的计数账本也不会被当作空文件重建。FrozenTurn 的恢复不需要重新申请模型时间窗口；现有内容摘要、版本、所有权和写入校验保持不变。
+
+这不是一个自动重放所有历史失败任务的迁移。旧 inbox 不会被清空；需要通过正常处理/重试入口继续处理，不能删除正确性状态来强行重新获取请求额度。
+
+## 只记录结构化耗时
+
+处理结果新增 `extraction_metrics`，后台 `process_status` 的 result/error 和尝试汇总保留同样的数字字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `target_duration_ms` | 固定观测目标 10000 毫秒，不参与失败判断 |
+| `turn_count` | 本次测量的 turn 尝试数量 |
+| `failed_turn_count` | 抛出处理异常的 turn 尝试数量 |
+| `over_target_turn_count` | 耗时超过目标的 turn 尝试数量，可能成功也可能失败 |
+| `successful_within_target_count` | 无处理异常且在目标内结算的尝试数量 |
+| `total_duration_ms` | 被测 turn 尝试的耗时之和 |
+| `max_turn_duration_ms` | 最慢一次 turn 尝试耗时 |
+| `planning_duration_ms` | 读取状态、准备上下文、模型调用和本地计划校验耗时 |
+| `commit_duration_ms` | 从进入提交阶段到提交和预算清理返回的耗时 |
+
+每轮计时从选中该 turn 后、读取其处理状态前开始。它不包括排队、worker 启动及 `process()` 开头的整批 inbox claim 扫描；不能把该指标冒充用户可见端到端耗时。跨 worker 重启会产生新的尝试，旧进程的 wall-clock 起点不再限制新进程执行。
+
+“无处理异常”包括合法 `NO_CHANGE` 和正常返回的部分处理；语义完整性仍由既有 `coverage_status`、deferred 数量、`memories_written` 和任务状态判断。因此耗时统计不替代提炼质量验收。快速失败不计入 `successful_within_target_count`。
+
+`model_metrics` 继续分别提供模型请求耗时、调用/修复次数和输入输出长度等信息。以上结构化统计不新增正文、prompt、response 或凭证存储。

{memleaf-0.2.42 → memleaf-0.2.44}/docs/general-processing.md

@@ -122,11 +122,15 @@ the preview. There is deliberately no apply-preview command.
 
 ## Verification boundaries
 
+The regression suite and acceptance helpers referenced here are maintained
+locally and are not included in this repository or its source distribution.
+Remote CI validates package construction and installed command entry points only.
+
 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
+accuracy. The local-only `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
@@ -142,20 +146,23 @@ that acceptance.
 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.
+The local-only Python suite is intended to run on all three OS families; remote
+CI does not exercise it. Native child-process tests cover Linux, macOS and
+Windows when run locally.
+
+Only the `install.sh` shell-harness class is POSIX-only; local Windows checks
+cover 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 explicitly configured model route using
+`MEMLEAF_LIVE_MODEL_TOKEN`, `MEMLEAF_LIVE_BASE_URL`, and `MEMLEAF_LIVE_MODEL`.
+Live acceptance tooling is maintained locally and is not run by remote CI.
+Missing configuration is a blocked acceptance result, not a passing semantic
+test. Never publish based only on deterministic mocks.
 
 ## Capture policy
 

{memleaf-0.2.42 → memleaf-0.2.44}/docs/processing-quality-acceptance.md

@@ -2,6 +2,11 @@
 
 This document defines acceptance for automatic memory extraction without treating one validation layer as proof of another.
 
+The deterministic suite and acceptance helpers described below are maintained
+locally and are not committed or shipped. Remote CI currently validates package
+construction and installed command entry points only; the layers below are not
+automatically exercised by that workflow.
+
 ## Invariants
 
 - Markdown under `knowledge/` remains the active-memory source of truth; `history/` remains historical state.
@@ -45,9 +50,12 @@ Required checks include:
 
 Passing this layer proves only the deterministic contracts under test.
 
-### 2. Cross-platform CI and MCP/background-runtime verification
+### 2. Cross-platform local regression and MCP/background-runtime verification
 
-Run the repository's supported OS matrix and the process-job/MCP tests. Verify that detached worker status exposes the bounded metrics, reruns aggregate metrics safely, and no model call is made while the Vault write lock is held.
+Run the maintained local-only test suite on supported OSes and the
+process-job/MCP tests. Verify that detached worker status exposes the bounded
+metrics, reruns aggregate metrics safely, and no model call is made while the
+Vault write lock is held.
 
 Passing this layer proves the tested runtime paths and platforms. It does not prove that a real model will always extract every business fact.
 

memleaf-0.2.44/examples/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+`basic_usage.py` runs entirely offline. Without `--vault` it creates a
+temporary vault; pass a directory explicitly when you want to inspect the
+generated Markdown after the process exits.
+
+The example shows a lightweight `context()` directory followed by an explicit
+`read_page()` call for the selected entry. Directory results contain no body;
+long bodies can be read in subsequent pages using `next_offset` and `version`.
+
+The `mcp_stdio.ndjson` file contains one legacy initialization request and one
+modern discovery request. Pipe it to the stdio adapter with an explicit vault:
+
+```sh
+python -m memleaf.mcp_server --vault <your-vault> < examples/mcp_stdio.ndjson
+```
+
+The NDJSON file is request-only and intentionally contains no tool call,
+network endpoint, local path, or secret.

{memleaf-0.2.42 → memleaf-0.2.44}/pyproject.toml

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

{memleaf-0.2.42 → memleaf-0.2.44}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.42"
+__version__ = "0.2.44"
 
 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.44/src/memleaf/extraction_budget.py

@@ -0,0 +1,199 @@
+"""Outbound-request accounting and advisory extraction latency metrics.
+
+Ten seconds is a performance target, not permission to cancel useful work or
+discard a valid memory. The transport owns the configured request timeout;
+this module only limits request count and observes complete-turn latency.
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, Iterable, Mapping
+
+from .llm import ModelError
+
+
+MAX_MODEL_REQUESTS = 2
+TARGET_TOTAL_SECONDS = 10.0
+
+
+class SinglePassBudgetBackend:
+    """Limit one logical B3 turn to two actual provider requests.
+
+    ``single_pass_safe`` routes map one complete() call to one request, without
+    hidden host-to-API fallback. The optional durable reservation preserves
+    consumed attempts across worker restarts. Neither the first request nor
+    its repair overrides the transport's configured ``llm.request_timeout``.
+    """
+
+    single_pass_safe = True
+
+    def __init__(
+        self,
+        backend: Any,
+        *,
+        reserve_request: Callable[[], int | None] | None = None,
+    ):
+        if not hasattr(backend, "complete"):
+            raise TypeError("single-pass backend must expose complete()")
+        if reserve_request is not None and not callable(reserve_request):
+            raise TypeError("reserve_request must be callable")
+        self._backend = backend
+        self._requests = 0
+        self._reserve_request = reserve_request
+
+    @property
+    def provider(self) -> str:
+        return str(getattr(self._backend, "provider", "unknown"))
+
+    @property
+    def model(self) -> str:
+        return str(getattr(self._backend, "model", "unknown"))
+
+    @property
+    def parallel_safe(self) -> bool:
+        return getattr(self._backend, "parallel_safe", False) is True
+
+    @property
+    def structured_batch_safe(self) -> bool:
+        return getattr(self._backend, "structured_batch_safe", False) is True
+
+    @property
+    def request_count(self) -> int:
+        return self._requests
+
+    def _request_ordinal(self, *, purpose: str) -> int:
+        if self._requests >= MAX_MODEL_REQUESTS:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        if self._reserve_request is None:
+            return self._requests + 1
+        try:
+            ordinal = self._reserve_request()
+        except Exception as error:
+            raise ModelError(
+                "single-pass extraction request budget cannot be reserved",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            ) from error
+        if type(ordinal) is not int or not 1 <= ordinal <= MAX_MODEL_REQUESTS:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        return ordinal
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        system: str = "",
+        purpose: str = "",
+        temperature: float = 0.0,
+    ) -> str:
+        self._request_ordinal(purpose=purpose)
+        # Count only after durable reservation succeeds. A kill from this point
+        # onward still consumes that attempt, without imposing a wall deadline.
+        self._requests += 1
+        return self._backend.complete(
+            prompt,
+            system=system,
+            purpose=purpose,
+            temperature=temperature,
+        )
+
+    def consume_call_metrics(self) -> dict[str, Any]:
+        consume = getattr(self._backend, "consume_call_metrics", None)
+        if not callable(consume):
+            return {}
+        try:
+            value = consume()
+        except Exception:
+            return {}
+        return dict(value) if isinstance(value, Mapping) else {}
+
+
+class ExtractionTiming:
+    """Observe one processing attempt; never authorize or reject a write.
+
+    This monotonic timer includes local planning/context, model work, validation
+    and commit. A worker restart begins a new measured attempt; persisted wall
+    timestamps from older releases are not latency-based write restrictions.
+    """
+
+    def __init__(self, *, clock: Any = None):
+        self._clock = time.monotonic if clock is None else clock
+        self._started = self._clock()
+        self._commit_started: float | None = None
+
+    def begin_commit(self) -> None:
+        self._commit_started = self._clock()
+
+    def finish(self, *, failed: bool = False) -> dict[str, int]:
+        ended = self._clock()
+        seconds = max(0.0, ended - self._started)
+        commit_started = self._commit_started
+        planning_end = ended if commit_started is None else commit_started
+        return {
+            "target_duration_ms": int(TARGET_TOTAL_SECONDS * 1000),
+            "turn_count": 1,
+            "failed_turn_count": int(failed),
+            "over_target_turn_count": int(seconds > TARGET_TOTAL_SECONDS),
+            "successful_within_target_count": int(not failed and seconds <= TARGET_TOTAL_SECONDS),
+            "total_duration_ms": int(seconds * 1000),
+            "max_turn_duration_ms": int(seconds * 1000),
+            "planning_duration_ms": int(max(0.0, planning_end - self._started) * 1000),
+            "commit_duration_ms": int(max(0.0, ended - planning_end) * 1000),
+        }
+
+
+def aggregate_extraction_metrics(values: Iterable[Mapping[str, Any]]) -> dict[str, int]:
+    """Sum allowlisted numeric metrics; never copy arbitrary content to status."""
+
+    summed = (
+        "turn_count", "failed_turn_count", "over_target_turn_count",
+        "successful_within_target_count", "total_duration_ms",
+        "planning_duration_ms", "commit_duration_ms",
+    )
+    result = {key: 0 for key in summed}
+    result["target_duration_ms"] = int(TARGET_TOTAL_SECONDS * 1000)
+    result["max_turn_duration_ms"] = 0
+    for value in values:
+        if not isinstance(value, Mapping):
+            continue
+        for key in (*summed, "max_turn_duration_ms"):
+            item = value.get(key)
+            if type(item) is not int or item < 0:
+                continue
+            if key == "max_turn_duration_ms":
+                result[key] = max(result[key], item)
+            else:
+                result[key] += item
+    return result
+
+
+def budget_single_pass_backend(
+    backend: Any,
+    *,
+    reserve_request: Callable[[], int | None] | None = None,
+) -> SinglePassBudgetBackend:
+    if isinstance(backend, SinglePassBudgetBackend):
+        return backend
+    return SinglePassBudgetBackend(
+        backend,
+        reserve_request=reserve_request,
+    )
+
+
+__all__ = [
+    "MAX_MODEL_REQUESTS",
+    "TARGET_TOTAL_SECONDS",
+    "ExtractionTiming",
+    "aggregate_extraction_metrics",
+    "SinglePassBudgetBackend",
+    "budget_single_pass_backend",
+]

{memleaf-0.2.42 → memleaf-0.2.44}/src/memleaf/extraction_capability.py

@@ -1,10 +1,9 @@
 """Capability checks for unified automatic extraction.
 
-Protocol compatibility and hard latency safety are intentionally separate.
-A backend may understand the B3 single-pass contract without being able to
-honor transport-level cancellation/deadlines. Automatic extraction can use
-one semantic protocol in both cases, while Processor applies the strict
-8/10-second budget only to ``single_pass_safe`` transports.
+Protocol compatibility and transport request accounting are separate.
+A backend may understand the B3 contract without exposing a bounded transport.
+``single_pass_safe`` identifies routes suitable for outbound-request counting;
+HTTP requests use the configured timeout, not the advisory ten-second target.
 """
 from __future__ import annotations
 
@@ -44,14 +43,14 @@ def _direct_protocol_capable(backend: Any) -> bool:
             return override
         # Raw Python callbacks are adapted by ModelExecutor into
         # CallableBackend. They can consume memleaf's B3 prompt, but are not
-        # strict-deadline safe because caller-owned code may ignore
+        # transport-timeout safe because caller-owned code may ignore
         # timeout/cancellation entirely.
         return True
     return False
 
 
 def supports_single_pass_protocol(backend: Any) -> bool:
-    """Return B3 protocol capability without claiming strict transport SLA."""
+    """Return B3 protocol capability without claiming transport guarantees."""
 
     if _direct_protocol_capable(backend):
         return True