python-hwpx 3.7.0__tar.gz → 3.8.0__tar.gz

{python_hwpx-3.7.0 → python_hwpx-3.8.0}/NOTICE

@@ -29,10 +29,22 @@ reimplemented from public references, without copying source code:
   from public model headers only. hwpxlib sample packages were used only as
   structure and roundtrip fixtures.
 
-These form-fill references were used as behavior evidence only. The
+- OpenBapul/hml-equation-parser (Apache-2.0): HULK-style EqEdit <-> LaTeX token
+  mapping, referenced for reader-direction <hp:equation> script rendering. The
+  token maps are a clean-room re-derivation from the public EqEdit grammar; no
+  source code was copied, translated, or vendored.
+
+These form-fill and equation references were used as behavior evidence only. The
 implementation is a clean-room Python implementation; no source code was
 copied, translated, vendored, or linked.
 
+## Optional dependency: latex2mathml
+
+The optional ``preview`` extra depends on roniemartinez/latex2mathml (MIT), used
+to convert LaTeX to MathML for the document preview viewer. It is an unmodified
+third-party dependency installed via pip; its MIT license travels with the
+package.
+
 ## Test fixtures: hwpxlib sample corpus
 
 tests/fixtures/hwpxlib_corpus/ contains .hwpx sample files vendored from

{python_hwpx-3.7.0/src/python_hwpx.egg-info → python_hwpx-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.7.0
+Version: 3.8.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -27,10 +27,13 @@ Requires-Dist: pillow>=10.0; extra == "visual"
 Requires-Dist: numpy>=1.26; extra == "visual"
 Provides-Extra: xlsx
 Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: preview
+Requires-Dist: latex2mathml>=3.77; extra == "preview"
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=4.0; extra == "dev"
 Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: latex2mathml>=3.77; extra == "dev"
 Provides-Extra: test
 Requires-Dist: build>=1.0; extra == "test"
 Requires-Dist: numpy>=1.26; extra == "test"
@@ -38,6 +41,7 @@ Requires-Dist: pillow>=10.0; extra == "test"
 Requires-Dist: pytest>=7.4; extra == "test"
 Requires-Dist: pytest-cov>=5.0; extra == "test"
 Requires-Dist: ruff>=0.12; extra == "test"
+Requires-Dist: latex2mathml>=3.77; extra == "test"
 Provides-Extra: typecheck
 Requires-Dist: mypy>=1.10; extra == "typecheck"
 Requires-Dist: pyright>=1.1.390; extra == "typecheck"
@@ -53,6 +57,8 @@ Dynamic: license-file
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
     <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
     <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
+    <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>
   </p>
 </p>
 
@@ -83,11 +89,10 @@ Dynamic: license-file
 | 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
 | 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
 
-`python-hwpx`는 HWPX 파싱·편집·생성을 제공하는 코어 라이브러리이며,
-`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
-“first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
+`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동
+구성요소입니다(유지보수 관계를 뜻하며, 한컴 등 외부 기관의 인증을 뜻하지 않습니다).
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.7.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.8.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
@@ -109,6 +114,11 @@ Dynamic: license-file
   export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
 - wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/images/redline-hancom.png" alt="python-hwpx가 남긴 변경추적과 AI 에이전트 메모가 실제 한/글에서 열린 화면" width="720">
+</p>
+<p align="center"><sub>python-hwpx로 작성한 변경추적(취소선·삽입)과 AI 에이전트 메모 — 실제 한/글에서 연 화면입니다.</sub></p>
+
 > 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
 > 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
 
@@ -301,6 +311,11 @@ Unsupported-but-preserved / Unsupported-and-rejected**.
 
 버그 리포트, 기능 제안, PR 모두 환영합니다.
 
+- **[help wanted 이슈](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — 지금 들어오기 좋은 입구입니다. 시작 전에 이슈에 코멘트로 방향을 남겨주세요.
+- **[마일스톤](https://github.com/airmang/python-hwpx/milestones)** — 공개 로드맵입니다. 프로젝트가 어디로 가는지 여기서 보입니다.
+- **[Discussions](https://github.com/airmang/python-hwpx/discussions)** — 질문·아이디어는 이슈 대신 여기로.
+- **[내부 실전 가이드](docs/internals/)** — HWPX 내부 구조가 처음이라면 여기부터. 개발 흐름은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다.
+
 ```bash
 git clone https://github.com/airmang/python-hwpx.git
 cd python-hwpx

{python_hwpx-3.7.0 → python_hwpx-3.8.0}/README.md

@@ -8,6 +8,8 @@
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
     <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
     <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
+    <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>
   </p>
 </p>
 
@@ -38,11 +40,10 @@
 | 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
 | 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
 
-`python-hwpx`는 HWPX 파싱·편집·생성을 제공하는 코어 라이브러리이며,
-`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
-“first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
+`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동
+구성요소입니다(유지보수 관계를 뜻하며, 한컴 등 외부 기관의 인증을 뜻하지 않습니다).
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.7.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.8.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
@@ -64,6 +65,11 @@
   export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
 - wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/images/redline-hancom.png" alt="python-hwpx가 남긴 변경추적과 AI 에이전트 메모가 실제 한/글에서 열린 화면" width="720">
+</p>
+<p align="center"><sub>python-hwpx로 작성한 변경추적(취소선·삽입)과 AI 에이전트 메모 — 실제 한/글에서 연 화면입니다.</sub></p>
+
 > 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
 > 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
 
@@ -256,6 +262,11 @@ Unsupported-but-preserved / Unsupported-and-rejected**.
 
 버그 리포트, 기능 제안, PR 모두 환영합니다.
 
+- **[help wanted 이슈](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — 지금 들어오기 좋은 입구입니다. 시작 전에 이슈에 코멘트로 방향을 남겨주세요.
+- **[마일스톤](https://github.com/airmang/python-hwpx/milestones)** — 공개 로드맵입니다. 프로젝트가 어디로 가는지 여기서 보입니다.
+- **[Discussions](https://github.com/airmang/python-hwpx/discussions)** — 질문·아이디어는 이슈 대신 여기로.
+- **[내부 실전 가이드](docs/internals/)** — HWPX 내부 구조가 처음이라면 여기부터. 개발 흐름은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다.
+
 ```bash
 git clone https://github.com/airmang/python-hwpx.git
 cd python-hwpx

{python_hwpx-3.7.0 → python_hwpx-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.7.0"
+version = "3.8.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -38,10 +38,16 @@ visual = [
 xlsx = [
     "openpyxl>=3.1",
 ]
+# Document preview viewer equation rendering: LaTeX -> MathML. Optional; without
+# it the preview fails closed to a LaTeX code block instead of dropping equations.
+preview = [
+    "latex2mathml>=3.77",
+]
 dev = [
     "build>=1.0",
     "twine>=4.0",
     "pytest>=7.4",
+    "latex2mathml>=3.77",
 ]
 test = [
     "build>=1.0",
@@ -50,6 +56,7 @@ test = [
     "pytest>=7.4",
     "pytest-cov>=5.0",
     "ruff>=0.12",
+    "latex2mathml>=3.77",
 ]
 typecheck = [
     "mypy>=1.10",
@@ -110,6 +117,12 @@ follow_imports = "skip"
 files = [
     "src/hwpx/document.py",
     "src/hwpx/mutation_report.py",
+    "src/hwpx/equation/__init__.py",
+    "src/hwpx/equation/tokens.py",
+    "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/mathml.py",
+    "src/hwpx/equation/render.py",
+    "src/hwpx/tools/document_viewer.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -158,6 +171,12 @@ ignore_missing_imports = true
 include = [
     "src/hwpx/document.py",
     "src/hwpx/mutation_report.py",
+    "src/hwpx/equation/__init__.py",
+    "src/hwpx/equation/tokens.py",
+    "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/mathml.py",
+    "src/hwpx/equation/render.py",
+    "src/hwpx/tools/document_viewer.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",

{python_hwpx-3.7.0 → python_hwpx-3.8.0}/src/hwpx/__init__.py

@@ -75,6 +75,10 @@ from .tools.layout_preview import (
     PreviewPage,
     render_layout_preview,
 )
+from .tools.document_viewer import (
+    DocumentViewer,
+    render_document_viewer,
+)
 from .ingest import (
     ConversionAttempt,
     DocumentConverter,
@@ -206,6 +210,8 @@ __all__ = [
     "validate_package",
     "paragraph_patch",
     "render_layout_preview",
+    "render_document_viewer",
+    "DocumentViewer",
     "register_template",
     "table_compute",
 ]

python_hwpx-3.8.0/src/hwpx/agent/_batch_verification.py

@@ -0,0 +1,383 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Verification/orchestration primitives for :func:`hwpx.agent.commands.apply_document_commands`.
+
+Split out of ``commands.py`` (S-088 P3, agent/commands.py:apply_document_commands
+complexity decomposition) to keep that module under its enforced line-count
+ratchet.  Everything here is self-contained -- it depends only on
+``hwpx.agent.model``/``hwpx.agent.document`` and absolute ``hwpx`` imports, never
+on ``commands.py`` itself, so ``commands.py`` can import from this module
+without creating an import cycle.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable, Mapping, MutableMapping
+from pathlib import Path
+from typing import Any
+
+from hwpx.document import HwpxDocument
+from hwpx.mutation_report import member_diff_bytes
+from hwpx.quality import QualityPolicy, SavePipeline
+from hwpx.tools.package_validator import validate_editor_open_safety
+
+from .document import HwpxAgentDocument
+from .model import AgentBatchResult, AgentContractError, AgentError
+
+_EMPTY_REVISION = "sha256:" + hashlib.sha256(b"").hexdigest()
+
+IdempotencyStore = MutableMapping[str, Any]
+FaultInjector = Callable[[str, int | None], None]
+DomainVerifier = Callable[[bytes, Mapping[str, Any]], Mapping[str, Any]]
+
+
+def _revision(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _error_from_exception(exc: BaseException, *, target: str | None = None) -> AgentError:
+    if isinstance(exc, AgentContractError):
+        code = exc.code
+        message = str(exc)
+        target = exc.target or target
+    elif isinstance(exc, (KeyError, IndexError, TypeError, ValueError)):
+        code = "invariant_violation"
+        message = str(exc) or type(exc).__name__
+    else:
+        code = "verification_failed"
+        message = f"{type(exc).__name__}: {exc}"
+    recoverability = "retryable" if code in {"stale_revision", "idempotency_conflict"} else "terminal"
+    if code in {"ambiguous_target", "volatile_target", "unsupported_content"}:
+        recoverability = "needs-review"
+    suggestions = {
+        "stale_revision": "Read the document again and retry with its current revision.",
+        "ambiguous_target": "Resolve a unique canonical path before mutation.",
+        "volatile_target": "Refresh the positional path from the current document revision.",
+        "unknown_property": "Use the node capability catalog to choose an editable property.",
+        "incompatible_parent": "Choose a compatible semantic parent and position.",
+        "verification_failed": "Inspect verificationReport and do not publish the candidate.",
+    }
+    return AgentError(
+        code=code,
+        message=message[:4096],
+        target=target,
+        recoverability=recoverability,
+        suggestion=suggestions.get(code),
+    )
+
+
+def _failure_result(
+    *,
+    exc: BaseException,
+    batch: Mapping[str, Any] | None,
+    input_revision: str = _EMPTY_REVISION,
+    command_results: list[Mapping[str, Any]] | None = None,
+    verification: Mapping[str, Any] | None = None,
+) -> AgentBatchResult:
+    raw = batch or {}
+    output = raw.get("output") if isinstance(raw, Mapping) else None
+    output_filename = ""
+    if isinstance(output, Mapping):
+        output_filename = str(output.get("filename") or "")
+    return AgentBatchResult(
+        ok=False,
+        rolled_back=True,
+        dry_run=bool(raw.get("dryRun", False)),
+        input_revision=input_revision,
+        document_revision=input_revision,
+        output_filename=output_filename,
+        command_results=tuple(command_results or ()),
+        verification_report=dict(verification or {}),
+        error=_error_from_exception(exc),
+    )
+
+
+def _quality_policy(value: str | Mapping[str, Any] | None) -> QualityPolicy:
+    if value is None or value == "transparent":
+        return QualityPolicy.transparent()
+    if value == "strict":
+        return QualityPolicy.strict()
+    if not isinstance(value, Mapping):  # already contract-validated
+        raise AgentContractError("invalid_syntax", "quality is invalid", target="batch.quality")
+    mode = value.get("mode", "transparent")
+    policy = QualityPolicy.strict() if mode == "strict" else QualityPolicy.transparent()
+    mapping = {
+        "renderCheck": "render_check",
+        "xsdMode": "xsd_mode",
+        "overflowPolicy": "overflow_policy",
+        "layoutLint": "layout_lint",
+        "preserveUnmodifiedParts": "preserve_unmodified_parts",
+        "requireReferenceIntegrity": "require_reference_integrity",
+    }
+    changes = {mapping[name]: setting for name, setting in value.items() if name in mapping}
+    return policy.with_(**changes)
+
+
+def _member_diff(before: bytes, after: bytes) -> dict[str, Any]:
+    # Shared with the Safe Write Contract's MutationReport spine: one uncompressed
+    # member comparison, one home for the diff shape (mutation_report.py).
+    return member_diff_bytes(before, after)
+
+
+def _verify_header_story_candidates(
+    candidate_data: bytes,
+    candidate_revision: str,
+    expectations: Mapping[str, Mapping[str, str]],
+) -> dict[str, Any]:
+    receipts: list[dict[str, Any]] = []
+    if expectations:
+        with HwpxDocument.open(candidate_data) as reopened:
+            view = HwpxAgentDocument.from_document(
+                reopened, revision=candidate_revision
+            )
+            for expectation in expectations.values():
+                path = expectation["path"]
+                binding = view._resolve_header_story(path)
+                if (
+                    binding.stable_id != expectation["stableId"]
+                    or binding.page_type != expectation["pageType"]
+                    or binding.text != expectation["text"]
+                ):
+                    raise AgentContractError(
+                        "verification_failed",
+                        "reopened header story does not match the committed binding",
+                        target=path,
+                    )
+                receipts.append(
+                    {
+                        "commandId": expectation["commandId"],
+                        "path": binding.path,
+                        "stableId": binding.stable_id,
+                        "pageType": binding.page_type,
+                        "textMatched": True,
+                    }
+                )
+    return {
+        "schemaVersion": "hwpx.agent-story-preservation/v1",
+        "ok": True,
+        "storyCount": len(receipts),
+        "stories": receipts,
+    }
+
+
+def _request_hash(batch: Mapping[str, Any]) -> str:
+    payload = json.dumps(
+        batch,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return _revision(payload)
+
+
+def _call_fault(injector: FaultInjector | None, stage: str, index: int | None = None) -> None:
+    if injector is not None:
+        injector(stage, index)
+
+
+def _apply_commands_idempotency_lookup(
+    verification: dict[str, Any],
+    idempotency_store: IdempotencyStore | None,
+    *,
+    key: str | None,
+    request_hash: str,
+) -> AgentBatchResult | None:
+    verification["idempotency"] = {
+        "keyProvided": key is not None,
+        "requestHash": request_hash,
+        "replayed": False,
+        "store": "caller-owned" if idempotency_store is not None else "none",
+    }
+    if key is not None and idempotency_store is not None and key in idempotency_store:
+        cached = idempotency_store[key]
+        if not isinstance(cached, Mapping) or cached.get("requestHash") != request_hash:
+            raise AgentContractError(
+                "idempotency_conflict",
+                "idempotency key was used for a different request",
+                target="batch.idempotencyKey",
+            )
+        prior = cached.get("result")
+        if not isinstance(prior, AgentBatchResult):
+            raise AgentContractError(
+                "invariant_violation", "idempotency store contains an invalid result", target="batch.idempotencyKey"
+            )
+        replay_report = dict(prior.verification_report)
+        replay_idempotency = dict(replay_report.get("idempotency", {}))
+        replay_idempotency["replayed"] = True
+        replay_report["idempotency"] = replay_idempotency
+        return AgentBatchResult(
+            ok=prior.ok,
+            rolled_back=prior.rolled_back,
+            dry_run=prior.dry_run,
+            input_revision=prior.input_revision,
+            document_revision=prior.document_revision,
+            output_filename=prior.output_filename,
+            command_results=prior.command_results,
+            semantic_diff=prior.semantic_diff,
+            verification_report=replay_report,
+            error=prior.error,
+        )
+    return None
+
+
+def _validate_apply_commands_input(
+    normalized: Mapping[str, Any],
+    verification: dict[str, Any],
+    input_data: bytes,
+    input_revision: str,
+    output_path: Path,
+) -> None:
+    verification["revision"] = {
+        "expected": normalized["expectedRevision"],
+        "actual": input_revision,
+        "matched": normalized["expectedRevision"] in {None, input_revision},
+    }
+    if normalized["expectedRevision"] not in {None, input_revision}:
+        raise AgentContractError(
+            "stale_revision", "expectedRevision does not match input bytes", target="batch.expectedRevision"
+        )
+    input_safety = validate_editor_open_safety(input_data)
+    verification["inputOpenSafety"] = input_safety.to_dict()
+    if not input_safety.ok:
+        raise AgentContractError(
+            "verification_failed",
+            "input failed package/reopen/openSafety verification",
+            target="batch.input.filename",
+        )
+    if output_path.exists() and not normalized["output"]["overwrite"] and not normalized["dryRun"]:
+        raise AgentContractError(
+            "invariant_violation", "output exists and overwrite is false", target="batch.output.filename"
+        )
+
+
+def _apply_commands_build_candidate_report(
+    input_data: bytes,
+    candidate_data: bytes,
+    input_revision: str,
+    semantic_changes: list[Mapping[str, Any]],
+    identity_changes: list[Mapping[str, str]],
+    story_expectations: Mapping[str, Mapping[str, str]],
+    verification: dict[str, Any],
+) -> tuple[str, dict[str, Any], Any, dict[str, Any]]:
+    """Compute the candidate revision/semantic diff and write byte/package safety
+    into ``verification``.
+
+    Does not raise on unsafe candidates -- the original ordering runs domain
+    verification before that check, so callers must still inspect the
+    returned ``safety``/``byte_report``.
+    """
+
+    candidate_revision = _revision(candidate_data)
+    if story_expectations:
+        verification["storyPreservation"] = _verify_header_story_candidates(
+            candidate_data,
+            candidate_revision,
+            story_expectations,
+        )
+    semantic_diff = {
+        "schemaVersion": "hwpx.agent-semantic-diff/v1",
+        "inputRevision": input_revision,
+        "candidateRevision": candidate_revision,
+        "changes": semantic_changes,
+        "identityMap": identity_changes,
+    }
+    byte_report = _member_diff(input_data, candidate_data)
+    safety = validate_editor_open_safety(candidate_data)
+    safety_dict = safety.to_dict()
+    verification.update(
+        {
+            "candidateRevision": candidate_revision,
+            "package": safety_dict["validatePackage"],
+            "reopen": safety_dict["reopen"],
+            "openSafety": safety_dict,
+            "semanticDiff": {"ok": True, "changeCount": len(semantic_changes)},
+            "bytePreservation": byte_report,
+        }
+    )
+    return candidate_revision, semantic_diff, safety, byte_report
+
+
+def _apply_commands_domain_verification(
+    candidate_data: bytes,
+    normalized: Mapping[str, Any],
+    requirements: set[str],
+    domain_verifier: DomainVerifier | None,
+    verification: dict[str, Any],
+) -> None:
+    if "domain" in requirements:
+        if domain_verifier is None:
+            verification["domain"] = {"ok": False, "error": "required verifier unavailable"}
+            raise AgentContractError(
+                "verification_failed", "required domain verifier is unavailable", target="domain"
+            )
+        domain_report = dict(domain_verifier(candidate_data, normalized))
+        try:
+            json.dumps(domain_report, ensure_ascii=False, sort_keys=True)
+        except (TypeError, ValueError) as exc:
+            raise AgentContractError(
+                "verification_failed",
+                "domain verifier returned a non-JSON report",
+                target="domain",
+            ) from exc
+        verification["domain"] = domain_report
+        if not domain_report.get("ok"):
+            raise AgentContractError("verification_failed", "domain verification failed", target="domain")
+    else:
+        verification["domain"] = {"ok": None, "status": "not-requested"}
+
+
+def _require_candidate_structural_safety(safety: Any, byte_report: Mapping[str, Any]) -> None:
+    if not safety.ok or not byte_report.get("ok"):
+        raise AgentContractError(
+            "verification_failed", "candidate failed package/reopen/openSafety verification"
+        )
+
+
+def _apply_commands_run_save_pipeline(
+    candidate_data: bytes,
+    input_path: Path,
+    output_path: Path,
+    document: HwpxDocument,
+    normalized: Mapping[str, Any],
+    requirements: set[str],
+    save_pipeline: SavePipeline | None,
+    verification: dict[str, Any],
+) -> Any:
+    pipeline = save_pipeline or SavePipeline()
+    quality_policy = _quality_policy(normalized["quality"])
+    if "realHancom" in requirements:
+        # Make the required oracle part of the atomic gate itself.  A
+        # post-publication provenance check would be too late to roll
+        # back an otherwise structurally valid file.
+        quality_policy = quality_policy.with_(
+            require_visual_complete=True,
+            render_check="required",
+        )
+    quality_report = pipeline.run(
+        candidate_data,
+        output_path=None if normalized["dryRun"] else output_path,
+        quality=quality_policy,
+        before=input_path,
+        reference_document=document,
+        publish="never" if normalized["dryRun"] else "on_pass",
+        source_label="agent.apply_document_commands",
+    )
+    verification["savePipeline"] = quality_report.to_dict()
+    verification["realHancom"] = {
+        "required": "realHancom" in requirements,
+        "ok": quality_report.visual_complete,
+        "status": quality_report.visual_complete_status,
+        "renderChecked": quality_report.render_checked,
+    }
+    if "realHancom" in requirements and not quality_report.visual_complete:
+        raise AgentContractError(
+            "verification_failed",
+            "required real-Hancom visual verification is unavailable or failed",
+            target="realHancom",
+        )
+    if not quality_report.ok:
+        raise AgentContractError(
+            "verification_failed", "SavePipeline rejected the candidate", target="savePipeline"
+        )
+    return quality_report