python-hwpx 3.7.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

hwpx/__init__.py

@@ -1,6 +1,18 @@
 # SPDX-License-Identifier: Apache-2.0
-"""High-level utilities for working with HWPX documents."""
+"""High-level utilities for working with HWPX documents.
 
+최상위 ``from hwpx import ...`` 표면은 세 계층으로 나뉩니다(정책·전수 목록:
+``docs/stable-api.md``):
+
+- **stable** — ``__all__``에 있는 이름. 계약이 굳었고 major 경계에서만 깨질 수 있음.
+- **experimental** — 계약이 유동적. ``from hwpx.experimental import ...``로 쓰세요.
+  최상위 재내보내기는 하위 호환을 위해 유지하되 접근 시 ``DeprecationWarning``이 나며
+  다음 major에서 제거될 예정입니다.
+- **deprecated** — 대체 경로로 이전하세요. 접근 시 ``DeprecationWarning``이 납니다.
+"""
+
+import importlib
+import warnings
 from importlib.metadata import PackageNotFoundError, version as _metadata_version
 
 
@@ -11,13 +23,94 @@ def _resolve_version() -> str:
     except PackageNotFoundError:
         return "0+unknown"
 
+
+# --- experimental / deprecated 최상위 표면 (지연 접근, 접근 시 경고) ---------------
+#
+# stable 이름은 아래에서 eager import 되어 모듈 전역에 존재하므로 ``__getattr__``이
+# 호출되지 않습니다(=경고 없음). 여기 등록된 이름만 지연 해석되어 경고를 냅니다.
+# 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
+
+_EXPERIMENTAL_EXPORTS = {
+    # 문서 ingestion 프레임워크(임의 포맷 -> HWPX). 계약 유동.
+    "ConversionAttempt": "hwpx.ingest",
+    "DocumentConverter": "hwpx.ingest",
+    "DocumentIngestError": "hwpx.ingest",
+    "DocumentIngestResult": "hwpx.ingest",
+    "DocumentIngestor": "hwpx.ingest",
+    "DocumentSourceInfo": "hwpx.ingest",
+    "UnsupportedDocumentFormat": "hwpx.ingest",
+    # 레이아웃 프리뷰(한컴 없는 정직 근사). 계약 유동.
+    "LayoutPreview": "hwpx.tools.layout_preview",
+    "PreviewPage": "hwpx.tools.layout_preview",
+    "render_layout_preview": "hwpx.tools.layout_preview",
+    # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
+    "DocumentViewer": "hwpx.tools.document_viewer",
+    "render_document_viewer": "hwpx.tools.document_viewer",
+}
+
+_DEPRECATED_EXPORTS = {
+    "analyze_template_formfit": "hwpx.template_formfit",
+    "apply_template_formfit": "hwpx.template_formfit",
+    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION": "hwpx.template_formfit",
+    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION": "hwpx.template_formfit",
+}
+
+# deprecated formfit 표면의 공통 대체 경로 안내.
+_FORMFIT_REPLACEMENT = (
+    "구조적 form-fill 경로를 사용하세요: 라이브러리는 "
+    "hwpx.table_patch.fill_cells 계열, MCP는 analyze_form_fill/apply_form_fill/"
+    "verify_form_fill."
+)
+
+
+def _experimental_message(name: str) -> str:
+    return (
+        f"'hwpx.{name}'는 실험적(experimental) 표면입니다. 계약이 유동적이므로 "
+        f"'from hwpx.experimental import {name}'로 import하세요. 최상위 재내보내기는 "
+        f"다음 major에서 제거될 예정입니다."
+    )
+
+
+def _deprecated_message(name: str) -> str:
+    return (
+        f"'hwpx.{name}'는 deprecated입니다. {_FORMFIT_REPLACEMENT} 이 이름은 "
+        f"다음 major에서 제거될 예정입니다."
+    )
+
+
 def __getattr__(name: str) -> object:
-    """Resolve dynamic module attributes."""
+    """Resolve dynamic module attributes.
+
+    ``__version__``은 경고 없이 지연 해석하고, experimental/deprecated 이름은
+    해석 시 ``DeprecationWarning``을 냅니다.
+    """
 
     if name == "__version__":
         return _resolve_version()
+
+    module_name = _EXPERIMENTAL_EXPORTS.get(name)
+    if module_name is not None:
+        warnings.warn(_experimental_message(name), DeprecationWarning, stacklevel=2)
+        return getattr(importlib.import_module(module_name), name)
+
+    module_name = _DEPRECATED_EXPORTS.get(name)
+    if module_name is not None:
+        warnings.warn(_deprecated_message(name), DeprecationWarning, stacklevel=2)
+        return getattr(importlib.import_module(module_name), name)
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
+
+def __dir__() -> list[str]:
+    return sorted(
+        set(globals())
+        | set(__all__)
+        | set(_EXPERIMENTAL_EXPORTS)
+        | set(_DEPRECATED_EXPORTS)
+    )
+
+
+# --- stable 최상위 표면 (eager import) ------------------------------------------
 from .tools.text_extractor import (
     DEFAULT_NAMESPACES,
     ParagraphInfo,
@@ -70,21 +163,8 @@ from .tools.style_profile import (
     placeholder_fill_report,
     register_template,
 )
-from .tools.layout_preview import (
-    LayoutPreview,
-    PreviewPage,
-    render_layout_preview,
-)
-from .ingest import (
-    ConversionAttempt,
-    DocumentConverter,
-    DocumentIngestError,
-    DocumentIngestResult,
-    DocumentIngestor,
-    DocumentSourceInfo,
-    HwpxMarkdownConverter,
-    UnsupportedDocumentFormat,
-)
+from .ingest import HwpxMarkdownConverter
+from .errors import HwpxError
 from .mutation_report import (
     MutationReport,
     PreservationDowngradeError,
@@ -120,12 +200,6 @@ from .quality import (
     SavePipeline,
     VisualCompleteReport,
 )
-from .template_formfit import (
-    TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION,
-    TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION,
-    analyze_template_formfit,
-    apply_template_formfit,
-)
 
 __all__ = [
     "QualityPolicy",
@@ -137,30 +211,21 @@ __all__ = [
     "DEFAULT_STYLE_PRESET",
     "DOCUMENT_PLAN_SCHEMA_VERSION",
     "get_document_plan_schema",
-    "ConversionAttempt",
     "DocumentBlock",
-    "DocumentConverter",
-    "DocumentIngestError",
-    "DocumentIngestResult",
-    "DocumentIngestor",
     "DocumentPlan",
-    "DocumentSourceInfo",
     "DocumentStylePreset",
     "EditorOpenSafetyReport",
     "ParagraphInfo",
     "PackageValidationReport",
     "BytePreservingPatchResult",
+    "HwpxError",
     "MutationReport",
     "PreservationDowngradeError",
     "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",
     "PatchSkipped",
-    "LayoutPreview",
-    "PreviewPage",
     "SectionInfo",
-    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION",
-    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION",
     "TextExtractor",
     "FoundElement",
     "HwpxMarkdownConverter",
@@ -173,7 +238,6 @@ __all__ = [
     "STYLE_PROFILE_SCHEMA_VERSION",
     "TEMPLATE_REGISTRY_SCHEMA_VERSION",
     "TABLE_COMPUTE_REPORT_VERSION",
-    "UnsupportedDocumentFormat",
     "apply_style_profile_to_plan",
     "build_comparison_table_plan",
     "build_image_grid",
@@ -186,8 +250,6 @@ __all__ = [
     "HwpxDocument",
     "HwpxPackage",
     "create_document_from_plan",
-    "analyze_template_formfit",
-    "apply_template_formfit",
     "approval_box",
     "describe_template",
     "extract_style_profile",
@@ -205,7 +267,6 @@ __all__ = [
     "validate_editor_open_safety",
     "validate_package",
     "paragraph_patch",
-    "render_layout_preview",
     "register_template",
     "table_compute",
 ]

hwpx/_document/persistence.py

@@ -3,10 +3,10 @@
 
 from __future__ import annotations
 
-import warnings
 from os import PathLike
 from typing import TYPE_CHECKING, Any, BinaryIO, Literal, Sequence
 
+from ..errors import SaveError
 from ..mutation_report import (
     Fallback,
     Mode,
@@ -84,7 +84,15 @@ def _run_pre_save_validation(doc: "HwpxDocument") -> None:
     report = doc.validate()
     if not report.ok:
         msgs = _summarize_validation_issues(report.issues)
-        raise ValueError(f"Document validation failed: {msgs}")
+        raise SaveError(
+            f"Document validation failed: {msgs}",
+            code="document-validation-failed",
+            context={"issueCount": len(report.issues), "issues": msgs},
+            suggestion=(
+                "Fix the reported schema issues, or disable validate_on_save if "
+                "the validation is a false positive for your document."
+            ),
+        )
 
 
 def _run_open_safety_validation(doc: "HwpxDocument", archive_bytes: bytes) -> None:
@@ -94,9 +102,15 @@ def _run_open_safety_validation(doc: "HwpxDocument", archive_bytes: bytes) -> No
 
     report = validate_editor_open_safety(archive_bytes)
     if not report.ok:
-        raise ValueError(
+        raise SaveError(
             "Generated HWPX package failed open-safety validation: "
-            + report.summary
+            + report.summary,
+            code="open-safety-failed",
+            context={"summary": report.summary},
+            suggestion=(
+                "The serialized package would not reopen in an HWPX editor; "
+                "inspect validate_editor_open_safety(...) for the failing checks."
+            ),
         )
 
 
@@ -126,7 +140,15 @@ def _gate_and_write(
     )
     if not report.ok:
         detail = "; ".join(str(error) for error in report.errors)
-        raise ValueError(f"Document save failed the quality gate: {detail}")
+        raise SaveError(
+            f"Document save failed the quality gate: {detail}",
+            code="quality-gate-failed",
+            context={"errors": [str(error) for error in report.errors]},
+            suggestion=(
+                "The SavePipeline quality gate rejected the archive; inspect the "
+                "returned report's errors before retrying."
+            ),
+        )
     return report
 
 
@@ -420,29 +442,3 @@ def _mark_save_clean(doc: "HwpxDocument") -> None:
     package = doc._package
     package._opened_members = dict(package._files)
     package._opened_zip_infos = dict(package._zip_infos)
-
-
-def save(
-    doc: "HwpxDocument",
-    path_or_stream: str | PathLike[str] | BinaryIO | None = None,
-) -> str | PathLike[str] | BinaryIO | bytes:
-    """Deprecated compatibility wrapper around save_to_path/save_to_stream/to_bytes.
-
-    Deprecated:
-        ``save()``는 하위 호환을 위해 유지되며 향후 제거될 수 있습니다.
-        - 경로 저장: ``save_to_path(path)``
-        - 스트림 저장: ``save_to_stream(stream)``
-        - 바이트 반환: ``to_bytes()``
-    """
-
-    warnings.warn(
-        "HwpxDocument.save()는 deprecated 예정입니다. "
-        "save_to_path()/save_to_stream()/to_bytes() 사용을 권장합니다.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    if path_or_stream is None:
-        return doc.to_bytes()
-    if isinstance(path_or_stream, (str, PathLike)):
-        return doc.save_to_path(path_or_stream)
-    return doc.save_to_stream(path_or_stream)

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