python-hwpx 2.13.0__tar.gz → 2.16.0__tar.gz

{python_hwpx-2.13.0/src/python_hwpx.egg-info → python_hwpx-2.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.13.0
+Version: 2.16.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -25,6 +25,8 @@ Provides-Extra: visual
 Requires-Dist: pymupdf>=1.24; extra == "visual"
 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: dev
 Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=4.0; extra == "dev"

{python_hwpx-2.13.0 → python_hwpx-2.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.13.0"
+version = "2.16.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -34,6 +34,10 @@ visual = [
     "pillow>=10.0",
     "numpy>=1.26",
 ]
+# Excel(.xlsx/.xlsm) 명부 ingestion for mail_merge. Lazy-imported; absent => clear error.
+xlsx = [
+    "openpyxl>=3.1",
+]
 dev = [
     "build>=1.0",
     "twine>=4.0",

{python_hwpx-2.13.0 → python_hwpx-2.16.0}/src/hwpx/__init__.py

@@ -94,6 +94,7 @@ from .authoring import (
     PlanValidationIssue,
     PlanValidationReport,
     create_document_from_plan,
+    get_document_plan_schema,
     inspect_document_authoring_quality,
     inspect_operating_plan_quality,
     normalize_document_plan,
@@ -121,6 +122,7 @@ __all__ = [
     "DEFAULT_NAMESPACES",
     "DEFAULT_STYLE_PRESET",
     "DOCUMENT_PLAN_SCHEMA_VERSION",
+    "get_document_plan_schema",
     "DocumentBlock",
     "DocumentPlan",
     "DocumentStylePreset",

{python_hwpx-2.13.0 → python_hwpx-2.16.0}/src/hwpx/authoring.py

@@ -265,6 +265,27 @@ def _plan_issue(
     )
 
 
+_PLAN_FAMILY_PREFIX = "hwpx.document_plan.v"
+
+
+def _is_forward_plan_version(version: str) -> bool:
+    """True if *version* is a newer same-family plan schema (forward-compat).
+
+    e.g. ``hwpx.document_plan.v3`` when the latest known is v2 — validate
+    best-effort with a warning rather than hard-rejecting.
+    """
+    if not version.startswith(_PLAN_FAMILY_PREFIX):
+        return False
+    suffix = version[len(_PLAN_FAMILY_PREFIX):]
+    if not suffix.isdigit():
+        return False
+    latest_known = max(
+        int(DOCUMENT_PLAN_SCHEMA_VERSION.rsplit("v", 1)[-1]),
+        int(DOCUMENT_PLAN_V2_SCHEMA_VERSION.rsplit("v", 1)[-1]),
+    )
+    return int(suffix) > latest_known
+
+
 def _plan_validation_report(
     issues: list[PlanValidationIssue],
     *,
@@ -449,6 +470,54 @@ def _plan_repair_hints(issues: tuple[PlanValidationIssue, ...]) -> list[dict[str
     return hints
 
 
+DOCUMENT_PLAN_SCHEMA_ID = "https://airmang.github.io/hwpx-plugins/schemas/document_plan.schema.json"
+
+
+def get_document_plan_schema() -> dict[str, Any]:
+    """Return a JSON Schema (draft 2020-12) for the declarative document plan.
+
+    Built live from the validator's own constants so it never drifts from the
+    accepted contract. Usable directly as an LLM Structured-Outputs / external
+    JSON-Schema-validation contract: it constrains the envelope (schemaVersion,
+    a non-empty ``blocks`` array, each block carrying a known ``type``) while
+    leaving block bodies open (``additionalProperties``) for forward-compat.
+    """
+
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": DOCUMENT_PLAN_SCHEMA_ID,
+        "title": "HWPX Document Plan",
+        "type": "object",
+        "required": ["schemaVersion", "blocks"],
+        "additionalProperties": True,
+        "properties": {
+            "schemaVersion": {
+                "type": "string",
+                "enum": [DOCUMENT_PLAN_SCHEMA_VERSION, DOCUMENT_PLAN_V2_SCHEMA_VERSION],
+                "description": "Plan schema version. Newer same-family versions validate best-effort.",
+            },
+            "title": {"type": "string"},
+            "metadata": {"type": "object"},
+            "blocks": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                    "type": "object",
+                    "required": ["type"],
+                    "additionalProperties": True,
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": sorted(_SUPPORTED_BLOCK_TYPES),
+                            "description": "Block kind. Body fields depend on the type.",
+                        }
+                    },
+                },
+            },
+        },
+    }
+
+
 def validate_document_plan(plan: Mapping[str, Any]) -> PlanValidationReport:
     """Return validation errors for a ``hwpx.document_plan.v1`` mapping."""
 
@@ -472,6 +541,31 @@ def validate_document_plan(plan: Mapping[str, Any]) -> PlanValidationReport:
 
     schema_version = str(plan.get("schemaVersion") or "").strip()
     if schema_version not in {DOCUMENT_PLAN_SCHEMA_VERSION, DOCUMENT_PLAN_V2_SCHEMA_VERSION}:
+        if _is_forward_plan_version(schema_version):
+            # Forward-compat: a newer same-family version warns and validates as
+            # the latest known schema (best-effort) instead of hard-rejecting, so
+            # a plan emitted against a newer schema still generates. Unknown newer
+            # fields are simply ignored by the v2 validator.
+            issues.append(
+                _plan_issue(
+                    "forward_schema_version",
+                    "schemaVersion",
+                    (
+                        f"schemaVersion {schema_version!r} is newer than the latest "
+                        f"known {DOCUMENT_PLAN_V2_SCHEMA_VERSION!r}; validating as "
+                        "latest known (best-effort)."
+                    ),
+                    severity="warning",
+                    suggestion="Unknown newer fields are ignored; verify the output.",
+                )
+            )
+            v2_report = _validate_document_plan_v2(
+                plan, schema_version=DOCUMENT_PLAN_V2_SCHEMA_VERSION
+            )
+            return _plan_validation_report(
+                [*issues, *v2_report.issues],
+                schema_version=schema_version,
+            )
         issues.append(
             _plan_issue(
                 "invalid_schema_version",
@@ -780,6 +874,138 @@ def _validate_v2_block(raw_block: Any, *, path: str) -> list[PlanValidationIssue
     return issues
 
 
+# --- M3 (S-057) document-type -> design profile routing ------------------------
+# Maps a plan's document_type (Korean label or profile id) to a committed
+# hwpx.design profile. When it resolves, create_document_from_plan composes from
+# the harvested, Hancom-opens-clean profile skeleton instead of the from-scratch
+# builder. Unknown types keep the legacy from-scratch path (regression-safe).
+_DOCTYPE_TO_PROFILE = {
+    "공문": "official_notice",
+    "공문서": "official_notice",
+    "official_notice": "official_notice",
+    "보고서": "report",
+    "report": "report",
+    "government_report": "report",
+    "가정통신문": "home_notice",
+    "home_notice": "home_notice",
+}
+_DOCTYPE_METADATA_KEYS = (
+    "document_type",
+    "문서 유형",
+    "문서유형",
+    "문서 종류",
+    "문서종류",
+    "documentType",
+)
+# 결문 (closing block) fields in their canonical render order.
+_GYEOLMUN_FIELDS = (
+    ("issuer", "발신명의"),
+    ("productionNumber", "생산등록번호"),
+    ("enforcementDate", "시행일"),
+    ("disclosure", "공개구분"),
+)
+
+
+def _plan_document_type(plan: Any) -> str:
+    """Read the plan's document type from metadata (preferred) or top level."""
+
+    if not isinstance(plan, Mapping):
+        return ""
+    metadata = plan.get("metadata")
+    metadata = metadata if isinstance(metadata, Mapping) else {}
+    for key in _DOCTYPE_METADATA_KEYS:
+        value = metadata.get(key) or plan.get(key)
+        if value:
+            return str(value).strip()
+    return ""
+
+
+def _resolve_design_profile(plan: Any) -> str | None:
+    """Return a committed design profile id for the plan's document_type, or None."""
+
+    raw = _plan_document_type(plan)
+    if not raw:
+        return None
+    from hwpx import design as _design
+
+    profile_id = _DOCTYPE_TO_PROFILE.get(raw)
+    if profile_id and profile_id in _design.available_profiles():
+        return profile_id
+    return None
+
+
+def _bridge_to_design_plan(plan: Mapping[str, Any], profile_id: str):
+    """Lower a document_plan mapping onto a :class:`hwpx.design.plan.DocumentPlan`.
+
+    Heading level 1 -> ``heading`` role, level >= 2 -> ``subheading``; paragraphs
+    and bullet items -> ``body``; tables -> an ``info`` table block. 결문 메타
+    fields are appended as trailing ``body`` blocks in canonical order (P0 proved
+    these survive a Hancom render).
+    """
+
+    from hwpx.design.plan import Block as _Block, DocumentPlan as _DesignPlan
+
+    blocks: list = []
+    for raw in plan.get("blocks") or []:
+        if not isinstance(raw, Mapping):
+            continue
+        block_type = str(raw.get("type") or "paragraph")
+        if block_type == "heading":
+            level = int(raw.get("level") or 1)
+            role = "heading" if level <= 1 else "subheading"
+            blocks.append(_Block(type="paragraph", role=role, text=str(raw.get("text") or "")))
+        elif block_type == "paragraph":
+            blocks.append(_Block(type="paragraph", role="body", text=str(raw.get("text") or "")))
+        elif block_type == "bullets":
+            for item in raw.get("items") or []:
+                blocks.append(_Block(type="paragraph", role="body", text=str(item)))
+        elif block_type == "table":
+            raw_cols = list(raw.get("columns") or raw.get("header") or [])
+            if raw_cols and isinstance(raw_cols[0], Mapping):
+                # document_plan schema: columns=[{key,label}], rows=[{key: value}]
+                keys = [str(c.get("key") or c.get("label") or "") for c in raw_cols]
+                columns = [str(c.get("label") or c.get("key") or "") for c in raw_cols]
+                rows = []
+                for row in raw.get("rows") or []:
+                    if isinstance(row, Mapping):
+                        rows.append([str(row.get(k, "")) for k in keys])
+                    elif isinstance(row, (list, tuple)):
+                        rows.append([str(c) for c in row])
+            else:
+                columns = [str(c) for c in raw_cols]
+                rows = [[str(c) for c in row] for row in (raw.get("rows") or [])]
+            blocks.append(_Block(type="table", role="info", columns=columns, rows=rows))
+        # page_break / memo: no design role -> skipped
+    gyeolmun = plan.get("gyeolmun")
+    if isinstance(gyeolmun, Mapping):
+        for key, label in _GYEOLMUN_FIELDS:
+            value = gyeolmun.get(key)
+            if value:
+                blocks.append(_Block(type="paragraph", role="body", text=f"{label}  {value}"))
+    return _DesignPlan(profile=profile_id, title=str(plan.get("title") or ""), blocks=blocks)
+
+
+def _korean_proofing_status(plan: Any, normalized_plan: "DocumentPlan | None") -> str:
+    """Honest 맞춤법/공공언어 status (Constitution V/IX) — never asserts 'passed'.
+
+    No free offline Korean spell/spacing oracle exists, so the default is
+    ``unverified``. If the plan signals an LLM self-proof pass it is labelled
+    ``llm_proofed_not_oracle_verified`` — proofed, but NOT oracle-verified.
+    """
+
+    metadata: Mapping[str, Any] = {}
+    if isinstance(plan, Mapping) and isinstance(plan.get("metadata"), Mapping):
+        metadata = plan["metadata"]
+    elif normalized_plan is not None:
+        metadata = normalized_plan.metadata
+    signal = str(
+        metadata.get("korean_proofing") or metadata.get("korean_proofing_status") or ""
+    ).strip().lower()
+    if signal in {"llm", "llm_proofed", "llm-proofed", "llm_proofed_not_oracle_verified"}:
+        return "llm_proofed_not_oracle_verified"
+    return "unverified"
+
+
 def create_document_from_plan(
     plan: Mapping[str, Any] | DocumentPlan,
     *,
@@ -787,6 +1013,19 @@ def create_document_from_plan(
 ) -> HwpxDocument:
     """Create a formatted HWPX document from a declarative document plan."""
 
+    if isinstance(plan, Mapping):
+        profile_id = _resolve_design_profile(plan)
+        if profile_id is not None:
+            from hwpx import design as _design
+
+            design_plan = _bridge_to_design_plan(plan, profile_id)
+            data, result = _design.compose_bytes(design_plan, production=True)
+            if not result.ok:
+                raise ValueError(
+                    f"profile compose failed for {profile_id!r}: {result.errors}"
+                )
+            return HwpxDocument.open(data)
+
     normalized = normalize_document_plan(plan)
     if normalized.builder_document is not None:
         return normalized.builder_document.lower()
@@ -858,8 +1097,15 @@ def inspect_document_authoring_quality(
     *,
     plan: Mapping[str, Any] | DocumentPlan | None = None,
     quality_profile: str | Mapping[str, Any] | None = None,
+    verify_render: bool = False,
 ) -> dict[str, Any]:
-    """Return deterministic structural quality evidence for generated HWPX."""
+    """Return deterministic structural quality evidence for generated HWPX.
+
+    When *verify_render* is true AND a Mac Hancom oracle is reachable, the
+    document is rendered and ``render_checked``/``visual_complete`` become real
+    receipts. Otherwise ``render_checked`` is ``False`` and ``visual_complete``
+    is ``"unverified"`` — never a silent true (Constitution V).
+    """
 
     normalized_plan: DocumentPlan | None = None
     plan_validation: dict[str, Any] | None = None
@@ -887,6 +1133,32 @@ def inspect_document_authoring_quality(
         package_report = validate_package(path if path is not None else package_payload)
         document_report = document.validate()
         reopened = _can_reopen(path, package_payload)
+        render_checked = False
+        visual_complete: Any = "unverified"
+        if verify_render:
+            from hwpx.visual import oracle as _oracle
+
+            _mac = _oracle.MacHancomOracle()
+            if _mac.available():
+                import tempfile as _tf
+
+                with _tf.TemporaryDirectory() as _tmp:
+                    _hwpx = Path(_tmp) / "render_check.hwpx"
+                    _hwpx.write_bytes(package_payload)
+                    _pdf = Path(_tmp) / "render_check.pdf"
+                    _rendered = _mac.render_pdf(str(_hwpx), str(_pdf))
+                    if _rendered and Path(_rendered).exists():
+                        try:
+                            import fitz as _fitz
+
+                            _doc = _fitz.open(_rendered)
+                            _has_text = any(pg.get_text().strip() for pg in _doc)
+                            _doc.close()
+                            render_checked = bool(_has_text)
+                            visual_complete = render_checked
+                        except Exception:
+                            render_checked = False
+                            visual_complete = "unverified"
         non_empty_texts = [
             (paragraph.text or "").strip()
             for paragraph in document.paragraphs
@@ -940,11 +1212,29 @@ def inspect_document_authoring_quality(
             and not profiles["operating_plan"].get("pass", False)
         ):
             gaps.append("operating plan quality failed")
+
+        document_type = ""
+        if isinstance(plan, Mapping):
+            document_type = _plan_document_type(plan)
+        elif normalized_plan is not None:
+            document_type = str(normalized_plan.metadata.get("document_type", "") or "")
+        gongmun_structure: dict[str, Any] | None = None
+        if _DOCTYPE_TO_PROFILE.get(document_type.strip()) == "official_notice":
+            from hwpx.tools.official_lint import (
+                inspect_official_document_style as _gongmun_lint,
+            )
+
+            gongmun_structure = _gongmun_lint(document, document_type="공문")
+            if not gongmun_structure.get("structure_pass", True):
+                gaps.append("공문 structure gate failed")
+        korean_proofing_status = _korean_proofing_status(plan, normalized_plan)
         return {
             "report_version": AUTHORING_REPORT_VERSION,
             "schemaVersion": DOCUMENT_PLAN_SCHEMA_VERSION,
             "plan_validation": plan_validation,
             "pass": not gaps,
+            "korean_proofing_status": korean_proofing_status,
+            "gongmun_structure": gongmun_structure,
             "block_counts": _block_counts(normalized_plan),
             "document": {
                 "paragraph_count": len(document.paragraphs),
@@ -952,6 +1242,8 @@ def inspect_document_authoring_quality(
                 "table_count": table_count,
                 "page_break_count": page_break_count,
             },
+            "render_checked": render_checked,
+            "visual_complete": visual_complete,
             "validation": {
                 "reopened": reopened,
                 "validate_package": {
@@ -970,7 +1262,7 @@ def inspect_document_authoring_quality(
             "style_token_usage": style_usage,
             "recovery": recovery,
             "profiles": profiles,
-            "visual_review_required": bool(gates.get("visualReviewRequired", True)),
+            "visual_review_required": bool(gates.get("visualReviewRequired", True)) and not render_checked,
             "gaps": gaps,
         }
     finally:

{python_hwpx-2.13.0 → python_hwpx-2.16.0}/src/hwpx/builder/__init__.py

@@ -20,10 +20,17 @@ from .core import (
     Table,
     approval_box,
 )
-from .report import BuilderSaveReport, ReopenReport
+from .report import (
+    FIDELITY_CONTRACT,
+    BuilderSaveReport,
+    BuilderVerifyReport,
+    ReopenReport,
+)
 
 __all__ = [
+    "FIDELITY_CONTRACT",
     "BuilderSaveReport",
+    "BuilderVerifyReport",
     "Bullet",
     "Document",
     "Footer",

{python_hwpx-2.13.0 → python_hwpx-2.16.0}/src/hwpx/builder/core.py

@@ -7,11 +7,14 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from hwpx.document import HwpxDocument
+from hwpx.tools.id_integrity import check_id_integrity
+from hwpx.tools.idempotence import IdempotenceReport, check_idempotent_pair
+from hwpx.tools.package_reconcile import reconcile_package_with_document
 from hwpx.tools.package_validator import validate_editor_open_safety
 from hwpx.tools.package_validator import validate_package
 from hwpx.tools.validator import validate_document
 
-from .report import BuilderSaveReport, ReopenReport
+from .report import BuilderSaveReport, BuilderVerifyReport, ReopenReport
 
 
 BuilderChild = (
@@ -805,3 +808,104 @@ class Document:
             visual_complete=visual_complete,
         )
         return report
+
+    def verify(self) -> BuilderVerifyReport:
+        """Dry, no-disk pre-write verification of the built document.
+
+        Lowers the document to bytes in memory and runs the save hard gates
+        (package, document, editor-open-safety, reopen) *plus* id-integrity and
+        a two-round idempotence check — a strictly stronger gate set than
+        :meth:`save_to_path` (whose report leaves id-integrity to the reader and
+        does not check idempotence) — without writing any file. Returns a
+        compact signal so a caller can branch on ``ok`` and read a
+        section/paragraph count before paying to materialize a real save.
+
+        Serialization itself can fail (e.g. open-safety rejects the output); in
+        that case this returns ``ok=False`` with ``serialize_error`` set rather
+        than raising, so a caller (fuzz loop, agent) can always branch on the
+        result.
+
+        See :data:`hwpx.builder.report.FIDELITY_CONTRACT` for what a green
+        verdict proves vs. does not prove.
+        """
+
+        try:
+            lowered = self.lower()
+            data = lowered.to_bytes()
+        except Exception as exc:  # the document cannot even be serialized
+            return BuilderVerifyReport(
+                ok=False,
+                reopen_ok=False,
+                package_ok=False,
+                document_ok=False,
+                editor_open_safety_ok=False,
+                id_integrity_ok=False,
+                idempotent=False,
+                sections_reconciled=False,
+                serialize_error=f"{type(exc).__name__}: {exc}",
+            )
+
+        package_report = validate_package(data)
+        document_report = validate_document(data)
+        editor_open_safety_report = validate_editor_open_safety(data)
+
+        reopened: HwpxDocument | None = None
+        reopen_error: str | None = None
+        try:
+            reopened = HwpxDocument.open(data)
+        except Exception as exc:  # surfaced in the report rather than raised
+            reopen_error = f"{type(exc).__name__}: {exc}"
+
+        id_integrity = (
+            check_id_integrity(reopened) if reopened is not None else None
+        )
+
+        # Fixed-point check on the EXACT bytes the gates above validated (gen-1)
+        # vs. their reopen-and-resave (gen-2), so the idempotence verdict refers
+        # to the bytes we would actually write, not a later generation.
+        idempotence: IdempotenceReport | None = None
+        serialize_error: str | None = None
+        try:
+            idempotence = check_idempotent_pair(data, HwpxDocument.open(data).to_bytes())
+        except Exception as exc:
+            serialize_error = f"{type(exc).__name__}: {exc}"
+
+        # Output-vs-intent: produced section parts must match the source model.
+        reconcile = reconcile_package_with_document(data, lowered)
+
+        package_ok = bool(getattr(package_report, "ok", False))
+        document_ok = bool(getattr(document_report, "ok", False))
+        editor_open_safety_ok = bool(getattr(editor_open_safety_report, "ok", False))
+        id_integrity_ok = bool(getattr(id_integrity, "ok", False))
+        idempotent = bool(idempotence is not None and idempotence.ok)
+        reopen_ok = reopened is not None
+        section_count = len(reopened.sections) if reopened is not None else 0
+        paragraph_count = len(reopened.paragraphs) if reopened is not None else 0
+
+        ok = (
+            package_ok
+            and document_ok
+            and editor_open_safety_ok
+            and id_integrity_ok
+            and reopen_ok
+            and idempotent
+            and reconcile.ok
+        )
+
+        return BuilderVerifyReport(
+            ok=ok,
+            reopen_ok=reopen_ok,
+            package_ok=package_ok,
+            document_ok=document_ok,
+            editor_open_safety_ok=editor_open_safety_ok,
+            id_integrity_ok=id_integrity_ok,
+            idempotent=idempotent,
+            sections_reconciled=reconcile.ok,
+            section_count=section_count,
+            paragraph_count=paragraph_count,
+            byte_length=len(data),
+            reopen_error=reopen_error,
+            serialize_error=serialize_error,
+            idempotence=idempotence,
+            reconcile=reconcile,
+        )

{python_hwpx-2.13.0 → python_hwpx-2.16.0}/src/hwpx/builder/report.py

@@ -7,10 +7,34 @@ from typing import Any
 
 from hwpx.quality import VisualCompleteReport
 from hwpx.tools.id_integrity import IdIntegrityReport, check_id_integrity
+from hwpx.tools.idempotence import IdempotenceReport
+from hwpx.tools.package_reconcile import PackageReconcileReport
 from hwpx.tools.package_validator import EditorOpenSafetyReport, PackageValidationReport
 from hwpx.tools.validator import ValidationReport
 
 
+# Explicit scope of what the builder's automated gates prove vs. don't, so a
+# green ``hard_gates`` is never mistaken for full Hancom/visual fidelity. The
+# gates answer "will Hancom likely open this", NOT "did every authored element
+# round-trip". Surfaced in every report's ``to_dict()``.
+FIDELITY_CONTRACT: dict[str, list[str]] = {
+    "proves": [
+        "package opens as a valid HWPX (mimetype/OPC structure, required entries)",
+        "no dangling id references or orphan BinData (id_integrity)",
+        "no known editor-open breakage patterns (editor_open_safety)",
+        "re-saving reproduces identical part contents (idempotent serialization)",
+        "the document reopens with our reader (reopen)",
+    ],
+    "does_not_prove": [
+        "visual layout fidelity in Hancom (line/page breaks, overlap) — needs the "
+        "visual oracle / ComputerUse",
+        "every authored element round-tripped byte-for-byte: merges, shapes, BinData "
+        "bytes, and equation script are not value-diffed",
+        "macOS Hancom acceptance for untested element combinations",
+    ],
+}
+
+
 @dataclass(frozen=True)
 class ReopenReport:
     """Result of reopening a generated document."""
@@ -56,6 +80,10 @@ class BuilderSaveReport:
             "path": str(self.path),
             "metadata": dict(self.metadata or {}),
             "hard_gates": dict(self.hard_gates),
+            "fidelity_contract": {
+                "proves": list(FIDELITY_CONTRACT["proves"]),
+                "does_not_prove": list(FIDELITY_CONTRACT["does_not_prove"]),
+            },
             "visual_review_required": self.visual_review_required,
             "feature_flags": dict(self.feature_flags),
             "visual_complete": (
@@ -113,3 +141,55 @@ class BuilderSaveReport:
                 }
             ),
         }
+
+
+@dataclass(frozen=True)
+class BuilderVerifyReport:
+    """Compact, no-disk pre-write verification signal from ``Document.verify()``.
+
+    Lowers the built document to bytes in memory and runs the same hard gates as
+    a real save plus a two-round idempotence check — without writing a file — so
+    a caller (agent, fuzz loop) can branch on ``ok`` before committing a path.
+    See :data:`FIDELITY_CONTRACT` for what these gates prove vs. don't.
+    """
+
+    ok: bool
+    reopen_ok: bool
+    package_ok: bool
+    document_ok: bool
+    editor_open_safety_ok: bool
+    id_integrity_ok: bool
+    idempotent: bool
+    sections_reconciled: bool = True
+    section_count: int = 0
+    paragraph_count: int = 0
+    byte_length: int = 0
+    reopen_error: str | None = None
+    serialize_error: str | None = None
+    idempotence: IdempotenceReport | None = None
+    reconcile: PackageReconcileReport | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "reopen_ok": self.reopen_ok,
+            "package_ok": self.package_ok,
+            "document_ok": self.document_ok,
+            "editor_open_safety_ok": self.editor_open_safety_ok,
+            "id_integrity_ok": self.id_integrity_ok,
+            "idempotent": self.idempotent,
+            "sections_reconciled": self.sections_reconciled,
+            "section_count": self.section_count,
+            "paragraph_count": self.paragraph_count,
+            "byte_length": self.byte_length,
+            "reopen_error": self.reopen_error,
+            "serialize_error": self.serialize_error,
+            "idempotence": (
+                None if self.idempotence is None else self.idempotence.to_dict()
+            ),
+            "reconcile": (None if self.reconcile is None else self.reconcile.to_dict()),
+            "fidelity_contract": {
+                "proves": list(FIDELITY_CONTRACT["proves"]),
+                "does_not_prove": list(FIDELITY_CONTRACT["does_not_prove"]),
+            },
+        }