memleaf 0.2.40__tar.gz → 0.2.41__tar.gz

{memleaf-0.2.40 → memleaf-0.2.41}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.41 — 2026-09-11
+
+- Promote the B3 single-pass automatic memory planner for explicitly `single_pass_safe` API backends. Core prepares bounded local retrieval/context once, one semantic planner stage decides CREATE / UPDATE / NO_CHANGE / DEFERRED, deterministic validation remains authoritative, and model-output repair is bounded to at most one retry (`max_attempts=2`). Host/custom/host-backed providers keep the proven P3 fallback, while explicit `remember` retains its existing single-summary path.
+- Make project Scope provenance Core-owned in the single-pass path. The model can no longer authorize `scope_source`; Core derives `user`, `session_context`, `insufficient_context`, or `model` from the selected scope set and applies deterministic grounding for model-derived project affiliation. Legacy model-provided `scope_source` is tolerated only for compatibility and ignored.
+- Carry forward the P0/P2/P3 transport reductions used by the fallback path, including bounded batch semantic review and CREATE-summary batching, while preserving Gate admission, target reconciliation, history/audit/commit semantics, idempotency, provider-neutral `thinking=low`, and fail-closed handling for invalid or unresolved evidence.
+- Remove committed long-run benchmark scripts/results/docs from `main` and split oversized admission, Hermes provider, and large regression-test modules by responsibility. This is repository-maintainability cleanup rather than a search-performance claim; regression coverage is retained rather than deleted.
+- Preserve the product architecture: Markdown under `knowledge/` remains the active-memory source of truth, `history/` remains historical state, permanent memory stays globally shared across agents using the same Vault, provenance/session fields do not become visibility filters, and no database, Redis, vector service, daemon, background resident service, or local-model dependency is introduced.
+- Validation for the integrated production tree passed the full Linux Python 3.11/3.12/3.13, Windows Python 3.11/3.12/3.13, macOS Python 3.11/3.13, wheel/sdist, installed-entry-point, Hermes/Codex host acceptance, and native Codex Windows/macOS matrices before release.
+
 ## 0.2.40 — 2026-09-09
 
 - Slim the automatic extraction stage prompts without changing output schemas, parsers, evidence segmentation, model routing, the provider-neutral `thinking=low` policy, target/revision handling, idempotency, or commit semantics. Gate owns admission, atomic splitting, attribution and duplicate/update selection; Summary writes one already-admitted current-state memory; semantic review verifies fidelity; Core keeps deterministic validation and write safety.

{memleaf-0.2.40/src/memleaf.egg-info → memleaf-0.2.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.40
+Version: 0.2.41
 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.40。**
+> **版本：0.2.41。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.40 → memleaf-0.2.41}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.40.**
+> **Version: 0.2.41.**
 > 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.40 → memleaf-0.2.41}/README.md

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

{memleaf-0.2.40 → memleaf-0.2.41}/pyproject.toml

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

{memleaf-0.2.40 → memleaf-0.2.41}/src/memleaf/__init__.py

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

@@ -14,6 +14,14 @@ import unicodedata
 from typing import Any, Iterable, Mapping
 
 from .validation import ModelOutputError, parse_strict_json
+from .evidence_syntax import (
+    _BULLET, _CLOSED_TASK, _EXAMPLE, _EXTERNAL_OWNER, _HEADING, _NEGATIVE_TASK,
+    _POLITE, _QUERY_START, _QUERY_WORD, _READ_ONLY_CONTROL, _clauses, _query,
+)
+from .evidence_structure import (
+    MAX_EXTERNAL_UNIT_BYTES, _EXTERNAL_MARKER, _external_blocks,
+    _has_external_structure, _structured_external_blocks,
+)
 
 
 # Tool capture already bounds ordinary records to 32 KiB. JSON and unstructured
@@ -21,38 +29,13 @@ from .validation import ModelOutputError, parse_strict_json
 # explicit plain-text structure may be split into bounded semantic sections.
 # Oversized legacy records are split only when necessary; every block retains
 # the original record identity in its EvidenceUnit metadata.
-MAX_EXTERNAL_UNIT_BYTES = 32 * 1024
 MAX_GATE_BATCH_UNITS = 8
 MAX_GATE_BATCH_BYTES = 64 * 1024
 
 # Syntax recognizers, not a catalogue of business scenarios or tool names.
-_POLITE = re.compile(r"^(?:(?:麻烦你|麻烦|请问|请|帮我|替我|劳驾)\s*)+")
-_QUERY_START = re.compile(
-    r"^(?:查询|查一下|查下|看看|看下|查看|阅读|读取|检查|汇总|列出|罗列|告诉我|梳理|盘点|总结|给我|"
-    r"把.+(?:列出|发我|告诉我|整理|汇总|梳理|总结)|(?:please\s+)?(?:list|show|tell|summari[sz]e|"
-    r"recap|check|find|what|which|who|when|where|why|how)\b)", re.I)
-_QUERY_WORD = re.compile(r"有没有|有什么|有哪些|是什么|是谁|多少|哪个|哪些|什么时候|何时|"
-                         r"如何|怎么|为什么|是否|能否|可否|\b(?:what|which|who|when|where|why|how)\b", re.I)
 # A complete, standalone control sentence that only tells memleaf not to
 # mutate memory is still a query.  Keep this deliberately narrow: project
 # constraints such as "不要修改数据库配置" remain user assertions.
-_READ_ONLY_CONTROL = re.compile(
-    r"^(?:(?:不要|不|请勿|勿)\s*(?:修改|更新|写入|保存|删除)\s*记忆|"
-    r"(?:please\s+)?(?:do\s+not|don['’]t)\s+(?:modify|update|write|save|delete)\s+memor(?:y|ies))$",
-    re.IGNORECASE,
-)
-_EXAMPLE = re.compile(r"(?:仅供.{0,8}(?:参考示例|示例|测试)|举(?:一个|个).{0,16}(?:例子|示例)|"
-                      r"(?:只是|以下是|这是|作为).{0,12}(?:示例|样例|模板|测试数据)|"
-                      r"假设|例如|测试数据|不要.{0,16}(?:记住|记录|当成真实))|"
-                      r"\b(?:example|hypothetical|suppose|fictional|test fixture)\b", re.I)
-_HEADING = re.compile(r"^\s*(?:#{1,6}\s+.+|\d+[.)、]\s*[^。;；\n]{1,100}[:：]\s*.*)$")
-_BULLET = re.compile(r"^\s*(?:[-*•]|\d+[.)、])\s+")
-_NEGATIVE_TASK = re.compile(r"无需|不需要|不用|不必|无须|毋须|(?:没有|不存在).{0,12}(?:需要|待办|问题)|"
-                            r"\b(?:no need|need not|not required|does not need|do not need)\b", re.I)
-_CLOSED_TASK = re.compile(r"(?:已|已经).{0,4}(?:全部|均)?(?:完成|取消|解决|关闭)|"
-                         r"\b(?:already (?:done|completed|cancelled)|all .{0,20}(?:resolved|completed))\b", re.I)
-_EXTERNAL_OWNER = re.compile(r"(?:客户|供应商|第三方)(?:自行|自己)?(?:需要|需|负责|必须|应当|要(?!求))|"
-                            r"\b(?:customer|vendor|supplier|third party)\s+(?:must|needs? to|is responsible)\b", re.I)
 
 
 @dataclass(frozen=True)
@@ -128,206 +111,12 @@ def partition_evidence_units(units: Iterable[EvidenceUnit]) -> EvidencePartition
     return EvidencePartition(tuple(physical), tuple(non_physical), tuple(unresolved))
 
 
-def _external_blocks(text: str) -> Iterable[tuple[int, int, str, str, tuple[str, ...]]]:
-    """Yield deterministic, exact source blocks for one external record.
 
-    JSON documents remain whole records.  Plain text that contains explicit
-    structure is divided at paragraphs, headings, numbered items and bullets
-    so coverage can account for each actionable item.  Ordinary prose and
-    line oriented logs remain whole records; punctuation never creates a
-    fragment.  The oversized fallback is byte bounded and always returns
-    Python character offsets.
-    """
 
-    stripped = text.lstrip()
-    is_json = False
-    if stripped.startswith(("{", "[")):
-        try:
-            json.loads(text)
-        except (TypeError, ValueError):
-            pass
-        else:
-            is_json = True
-
-    # Explicit record dividers delimit complete observations in a batched
-    # text result. Keep each record's header and paragraphs together so they
-    # cannot drift into unrelated model batches. This recognizes layout only;
-    # it assigns no business meaning, owner, scope or source authority.
-    dividers = list(re.finditer(r"(?m)^[ \t]*(?:={8,}|-{8,}|\*{8,})[ \t]*\r?$", text)) if not is_json else []
-    if dividers:
-        boundaries = sorted({0, *(match.start() for match in dividers), len(text)})
-        for left, right in zip(boundaries, boundaries[1:]):
-            block = text[left:right]
-            if not block.strip():
-                continue
-            if re.fullmatch(r"[ \t]*(?:={8,}|-{8,}|\*{8,})[ \t\r\n]*", block):
-                continue
-            # A divider is structural context, not an independent assertion.
-            if len(block.encode("utf-8")) <= MAX_EXTERNAL_UNIT_BYTES:
-                yield left, right, block, "external_record", ()
-            else:
-                # Avoid recursively recognizing the same leading divider.
-                cursor = left
-                while cursor < right:
-                    end = cursor
-                    size = 0
-                    while end < right:
-                        width = len(text[end].encode("utf-8"))
-                        if end > cursor and size + width > MAX_EXTERNAL_UNIT_BYTES:
-                            break
-                        size += width
-                        end += 1
-                    yield cursor, end, text[cursor:end], "external_block", ()
-                    cursor = end
-        return
-
-    if len(text.encode("utf-8")) <= MAX_EXTERNAL_UNIT_BYTES and (
-        is_json or not _has_external_structure(text)
-    ):
-        yield 0, len(text), text, "external_record", ()
-        return
-
-    if len(text.encode("utf-8")) <= MAX_EXTERNAL_UNIT_BYTES:
-        yield from _structured_external_blocks(text)
-        return
-
-    start = 0
-    while start < len(text):
-        end = start
-        encoded = 0
-        while end < len(text):
-            width = len(text[end].encode("utf-8"))
-            if end > start and encoded + width > MAX_EXTERNAL_UNIT_BYTES:
-                break
-            encoded += width
-            end += 1
-        if end <= start:
-            # A single code point larger than the budget is impossible for a
-            # normal Unicode scalar, but make progress defensively.
-            end = min(start + 1, len(text))
-        yield start, end, text[start:end], "external_block", ()
-        start = end
-
-
-_EXTERNAL_MARKER = re.compile(r"^\s*(?:#{1,6}\s+|[-*+•]\s+|\d+[.)、]\s+)")
-
-
-def _has_external_structure(text: str) -> bool:
-    """Recognize structural boundaries without treating every line as one."""
-
-    if "\n\n" in text or "\r\n\r\n" in text:
-        return True
-    for line in text.splitlines():
-        value = line.strip()
-        if not value:
-            continue
-        if _EXTERNAL_MARKER.match(line) or value.endswith((":", "：")):
-            return True
-    return False
-
-
-def _structured_external_blocks(
-    text: str,
-) -> Iterable[tuple[int, int, str, str, tuple[str, ...]]]:
-    """Split explicit text structure while retaining parent section context."""
-
-    # ``splitlines(True)`` keeps offsets exact while allowing us to discard
-    # only structural whitespace at each emitted boundary.
-    lines: list[tuple[int, int, str, str]] = []
-    cursor = 0
-    for raw in text.splitlines(True):
-        line_end = cursor + len(raw)
-        body = raw[:-1] if raw.endswith("\n") else raw
-        if body.endswith("\r"):
-            body = body[:-1]
-        lines.append((cursor, line_end, body, raw))
-        cursor = line_end
-    if cursor < len(text):
-        lines.append((cursor, len(text), text[cursor:], text[cursor:]))
-    if not lines:
-        return
-
-    # Stack entries are ``(indent, label, kind)``. Headings remain in scope for
-    # sibling numbered items; prior items only remain in scope for indented
-    # children such as the two Morgan bullets in the regression digest.
-    contexts: list[tuple[int, str, str]] = []
-    current_start: int | None = None
-    current_end: int | None = None
-    current_section: tuple[str, ...] = ()
-    current_syntax = "external_paragraph"
-
-    def emit_current() -> tuple[int, int, str, str, tuple[str, ...]] | None:
-        if current_start is None or current_end is None or current_start >= current_end:
-            return None
-        return (
-            current_start,
-            current_end,
-            text[current_start:current_end],
-            current_syntax,
-            current_section,
-        )
 
-    for line_start, line_end, body, raw in lines:
-        left = len(body) - len(body.lstrip())
-        right = len(body.rstrip())
-        value = body.strip()
-        if not value:
-            emitted = emit_current()
-            if emitted is not None:
-                yield emitted
-            current_start = current_end = None
-            current_section = ()
-            current_syntax = "external_paragraph"
-            continue
 
-        indent = left
-        marker = _EXTERNAL_MARKER.match(body)
-        heading = bool(re.match(r"^\s*#{1,6}\s+", body)) or (
-            not marker and value.endswith((":", "："))
-        )
-        structural = bool(marker) or heading
-        if structural:
-            emitted = emit_current()
-            if emitted is not None:
-                yield emitted
-            current_start = line_start + left
-            current_end = line_start + right
-            current_syntax = "external_section"
-
-            if heading:
-                contexts = [
-                    (level, label, kind)
-                    for level, label, kind in contexts
-                    if level < indent
-                ]
-                current_section = tuple(label for _, label, _ in contexts)
-                contexts.append((indent, value, "heading"))
-            else:
-                # Same-level numbered/bullet siblings replace the previous
-                # item, while a heading at that level remains their context.
-                contexts = [
-                    (level, label, kind)
-                    for level, label, kind in contexts
-                    if level < indent or (level == indent and kind == "heading")
-                ]
-                current_section = tuple(label for _, label, _ in contexts)
-                contexts.append((indent, value, "item"))
-            continue
 
-        # Non-structural lines continue the current item/paragraph. This keeps
-        # wrapped prose together and avoids turning line-oriented logs into one
-        # evidence unit per line.
-        line_content_start = line_start + left
-        line_content_end = line_start + right
-        if current_start is None:
-            current_start = line_content_start
-            current_section = tuple(label for _, label, _ in contexts)
-            current_syntax = "external_paragraph"
-        current_end = line_content_end
 
-    emitted = emit_current()
-    if emitted is not None:
-        yield emitted
 
 
 def gate_evidence_batches(
@@ -366,38 +155,8 @@ def gate_evidence_batches(
     return tuple(batches) if batches else ((),)
 
 
-def _query(text: str) -> bool:
-    text = _POLITE.sub("", text.strip())
-    control = text.rstrip("。！？!?；;.! ")
-    if _READ_ONLY_CONTROL.fullmatch(control):
-        return True
-    return bool(_QUERY_START.search(text) or _QUERY_WORD.search(text)
-                or re.search(r"[?？]|(?:吗|么|呢)[。！!\s]*$", text))
 
 
-def _clauses(text: str) -> Iterable[tuple[str, tuple[str, ...], bool]]:
-    """Separate syntax while retaining headings as context, never as ownership."""
-    section: tuple[str, ...] = ()
-    in_code = False
-    for line in text.splitlines():
-        line = line.strip()
-        if line.startswith("```") or line.startswith("~~~"):
-            in_code = not in_code
-            continue
-        if not line:
-            continue
-        if _HEADING.match(line):
-            # Every heading resets context, including unregistered names.
-            section = (re.sub(r"^(?:#{1,6}|\d+[.)、])\s*", "", line).split(":", 1)[0].split("：", 1)[0],)
-        quoted = in_code or line.startswith(">")
-        line = _BULLET.sub("", line)
-        # Independent assertion/query clauses must not suppress one another.
-        # Do not split numeric thousands separators.
-        line = re.sub(r"(?<![0-9])[,，]\s*|[,，](?![0-9])\s*", "\n", line)
-        for clause in re.split(r"(?<=[。!?！？;；])\s*|\n+|(?<=[A-Za-z0-9]\.)\s+", line):
-            clause = clause.strip()
-            if clause:
-                yield clause, section, quoted
 
 
 def analyze_turn_evidence(events: Iterable[Mapping[str, Any]]) -> tuple[EvidenceUnit, ...]:
@@ -790,6 +549,12 @@ def parse_coverage(
                     validation_detail="invalid_evidence",
                     evidence_check="coverage_terminal_witness",
                 )
+            if set(row) != {"unit_id", "decision", "candidate_ids"}:
+                raise ModelOutputError(
+                    "invalid coverage candidate shape",
+                    validation_detail="invalid_evidence",
+                    evidence_check="coverage_shape",
+                )
             if not units[uid].can_support or not isinstance(ids, list) or not ids or any(not isinstance(i, str) or i not in candidates for i in ids):
                 raise ModelOutputError("invalid coverage candidate", validation_detail="invalid_evidence",
                                        evidence_check="coverage_candidate")
@@ -825,6 +590,15 @@ def parse_coverage(
                     validation_detail="invalid_evidence",
                     evidence_check="coverage_terminal_witness",
                 )
+            expected_fields = ({"unit_id", "decision", "reason", "memory_id"}
+                               if reason == "already_completed"
+                               else {"unit_id", "decision", "reason"})
+            if set(row) != expected_fields:
+                raise ModelOutputError(
+                    "invalid coverage decision shape",
+                    validation_detail="invalid_evidence",
+                    evidence_check="coverage_shape",
+                )
             # Normalize only the model's declared reason. This keeps the
             # protocol source-neutral: no local topic or business heuristic
             # decides whether a fragment is retryable.

memleaf-0.2.41/src/memleaf/batch_review.py

@@ -0,0 +1,205 @@
+"""Bounded batch transport for independent automatic semantic reviews.
+
+The semantic contract and per-item summary parser remain the existing single-review
+ones. Batching changes only transport granularity: up to four independent reviews
+share one model call. A malformed associated row is retried as one legacy single
+review; an un-associable batch envelope falls back to legacy singles for the whole
+chunk. No Vault or audit mutation occurs here.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable, Mapping
+
+from .llm import ModelError
+from .update_review import (
+    CREATE_SEMANTIC_REVIEW_SYSTEM,
+    UPDATE_SEMANTIC_REVIEW_SYSTEM,
+    _MAX_PROMPT_BYTES,
+    _complete_json_stage_compat,
+    _json_safe,
+    _source_projection,
+    _target_projection,
+    parse_update_review_output,
+    review_create,
+    review_update,
+)
+from .validation import ModelOutputError, parse_strict_json
+
+MAX_REVIEW_BATCH_ITEMS = 4
+
+_CREATE_BATCH_SYSTEM = CREATE_SEMANTIC_REVIEW_SYSTEM + """
+
+BATCH MODE: the single-review semantic rules above apply independently to each
+input row. This mode changes only the outer transport shape. Return exactly
+{"reviews":[...]} with one row per supplied review_id. Each row must copy its
+review_id exactly and then contain exactly the fields of one legal single-review
+response. Do not transfer facts, decisions, Scope, targets, or evidence between
+rows. Row order is irrelevant; review_id is the association key. Return JSON only.
+"""
+
+_UPDATE_BATCH_SYSTEM = UPDATE_SEMANTIC_REVIEW_SYSTEM + """
+
+BATCH MODE: the single-review semantic rules above apply independently to each
+input row. This mode changes only the outer transport shape. Return exactly
+{"reviews":[...]} with one row per supplied review_id. Each row must copy its
+review_id exactly and then contain exactly the fields of one legal single-review
+response. Do not transfer facts, decisions, Scope, targets, or evidence between
+rows. Row order is irrelevant; review_id is the association key. Return JSON only.
+"""
+
+
+def _validated_specs(items: Iterable[Mapping[str, Any]], *, update: bool) -> list[dict[str, Any]]:
+    specs = [dict(item) for item in items]
+    if not specs or len(specs) > MAX_REVIEW_BATCH_ITEMS:
+        raise ValueError("review batch must contain between one and four items")
+    seen: set[str] = set()
+    for spec in specs:
+        review_id = spec.get("review_id")
+        if not isinstance(review_id, str) or not review_id or review_id in seen:
+            raise ValueError("review batch requires unique non-empty review_id values")
+        seen.add(review_id)
+        if not callable(spec.get("parse_summary")):
+            raise ValueError("review batch item requires parse_summary")
+        if not isinstance(spec.get("proposed_summary"), Mapping):
+            raise ValueError("review batch item requires proposed_summary")
+        source = spec.get("admitted_source")
+        if isinstance(source, (str, bytes)) or source is None:
+            raise ValueError("review batch item requires admitted_source")
+        if update and spec.get("target") is None:
+            raise ValueError("update review batch item requires target")
+    return specs
+
+
+def _batch_payload(specs: list[dict[str, Any]], *, update: bool) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for spec in specs:
+        row = {
+            "review_id": spec["review_id"],
+            "admitted_source": _source_projection(spec["admitted_source"]),
+            "proposed_summary": _json_safe(dict(spec["proposed_summary"])),
+        }
+        if update:
+            row["active_target"] = _target_projection(spec["target"])
+        rows.append(row)
+    return rows
+
+
+def _build_batch_prompt(specs: list[dict[str, Any]], *, update: bool) -> str:
+    mode = "UPDATE" if update else "CREATE"
+    payload = {"reviews": _batch_payload(specs, update=update)}
+    prompt = (
+        f"{mode}_SEMANTIC_REVIEW_BATCH\n"
+        + json.dumps(_json_safe(payload), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        + "\n\nReview each row independently and return the strict batch object."
+    )
+    if len(prompt.encode("utf-8")) > _MAX_PROMPT_BYTES:
+        raise ModelOutputError(
+            "semantic review batch input exceeds prompt budget",
+            validation_detail="other_schema_violation",
+        )
+    return prompt
+
+
+def _parse_batch_output(raw: Any, specs: list[dict[str, Any]]) -> dict[str, Any]:
+    value = parse_strict_json(raw) if isinstance(raw, str) else raw
+    if not isinstance(value, Mapping) or set(value) != {"reviews"} or not isinstance(value["reviews"], list):
+        raise ModelOutputError("invalid semantic review batch envelope", validation_detail="root_shape")
+    by_id = {spec["review_id"]: spec for spec in specs}
+    seen: set[str] = set()
+    outcomes: dict[str, dict[str, Any]] = {}
+    retry_ids: list[str] = []
+    for row in value["reviews"]:
+        if not isinstance(row, Mapping):
+            raise ModelOutputError("unassociated semantic review batch row", validation_detail="root_shape")
+        review_id = row.get("review_id")
+        if not isinstance(review_id, str) or review_id not in by_id or review_id in seen:
+            raise ModelOutputError("invalid semantic review batch membership", validation_detail="invalid_evidence")
+        seen.add(review_id)
+        single = {key: item for key, item in row.items() if key != "review_id"}
+        try:
+            outcome = parse_update_review_output(
+                single,
+                parse_summary=by_id[review_id]["parse_summary"],
+            )
+        except ModelOutputError:
+            retry_ids.append(review_id)
+        else:
+            outcomes[review_id] = outcome
+    for spec in specs:
+        if spec["review_id"] not in seen:
+            retry_ids.append(spec["review_id"])
+    return {"outcomes": outcomes, "retry_ids": retry_ids}
+
+
+def _single(model_executor: Any, backend: Any, spec: Mapping[str, Any], *, update: bool) -> dict[str, Any]:
+    kwargs = {
+        "admitted_source": spec["admitted_source"],
+        "proposed_summary": spec["proposed_summary"],
+        "parse_summary": spec["parse_summary"],
+        "diagnostic_context": spec.get("diagnostic_context"),
+    }
+    if update:
+        return review_update(model_executor, backend, target=spec["target"], **kwargs)
+    return review_create(model_executor, backend, **kwargs)
+
+
+def _review_batch(
+    model_executor: Any,
+    backend: Any,
+    items: Iterable[Mapping[str, Any]],
+    *,
+    update: bool,
+) -> list[dict[str, Any]]:
+    specs = _validated_specs(items, update=update)
+    if getattr(backend, "structured_batch_safe", False) is not True:
+        return [_single(model_executor, backend, spec, update=update) for spec in specs]
+    if len(specs) == 1:
+        return [_single(model_executor, backend, specs[0], update=update)]
+    try:
+        prompt = _build_batch_prompt(specs, update=update)
+        parsed = _complete_json_stage_compat(
+            model_executor,
+            backend,
+            prompt,
+            system=_UPDATE_BATCH_SYSTEM if update else _CREATE_BATCH_SYSTEM,
+            purpose="summarize",
+            parser=lambda raw: _parse_batch_output(raw, specs),
+            diagnostic_context=specs[0].get("diagnostic_context"),
+            metric_stage="semantic_review",
+        )
+        if not isinstance(parsed, Mapping):
+            raise ModelOutputError("invalid semantic review batch result", validation_detail="root_shape")
+        outcomes = parsed.get("outcomes")
+        retry_ids = parsed.get("retry_ids")
+        if not isinstance(outcomes, Mapping) or not isinstance(retry_ids, list):
+            raise ModelOutputError("invalid semantic review batch result", validation_detail="root_shape")
+    except (ModelOutputError, TypeError, ValueError):
+        return [_single(model_executor, backend, spec, update=update) for spec in specs]
+
+    resolved = {key: dict(value) for key, value in outcomes.items() if isinstance(key, str) and isinstance(value, Mapping)}
+    retry_set = {value for value in retry_ids if isinstance(value, str)}
+    for spec in specs:
+        review_id = spec["review_id"]
+        if review_id in retry_set or review_id not in resolved:
+            resolved[review_id] = _single(model_executor, backend, spec, update=update)
+    return [resolved[spec["review_id"]] for spec in specs]
+
+
+def review_create_batch(model_executor: Any, backend: Any, items: Iterable[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    """Review up to four independent CREATE requests with per-row fallback."""
+
+    return _review_batch(model_executor, backend, items, update=False)
+
+
+def review_update_batch(model_executor: Any, backend: Any, items: Iterable[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    """Review up to four independent UPDATE requests with per-row fallback."""
+
+    return _review_batch(model_executor, backend, items, update=True)
+
+
+__all__ = [
+    "MAX_REVIEW_BATCH_ITEMS",
+    "review_create_batch",
+    "review_update_batch",
+]