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

hwpx/__init__.py

@@ -85,6 +85,10 @@ from .ingest import (
     HwpxMarkdownConverter,
     UnsupportedDocumentFormat,
 )
+from .mutation_report import (
+    MutationReport,
+    PreservationDowngradeError,
+)
 from .patch import (
     BytePreservingPatchResult,
     ParagraphTextPatch,
@@ -146,6 +150,8 @@ __all__ = [
     "ParagraphInfo",
     "PackageValidationReport",
     "BytePreservingPatchResult",
+    "MutationReport",
+    "PreservationDowngradeError",
     "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",

hwpx/_document/persistence.py

@@ -5,8 +5,18 @@ from __future__ import annotations
 
 import warnings
 from os import PathLike
-from typing import TYPE_CHECKING, Any, BinaryIO, Sequence
-
+from typing import TYPE_CHECKING, Any, BinaryIO, Literal, Sequence
+
+from ..mutation_report import (
+    Fallback,
+    Mode,
+    MutationReport,
+    PreservationDowngradeError,
+    PreservationMeasurement,
+    VerificationSummary,
+    VerificationValue,
+    measure_save,
+)
 from ..opc.package import _UNCHECKED_SAVE_TOKEN
 from ..quality import QualityPolicy
 from ..quality.report import OpenSafetyReport
@@ -120,27 +130,178 @@ def _gate_and_write(
     return report
 
 
-def save_to_path(doc: "HwpxDocument", path: str | PathLike[str]) -> str | PathLike[str]:
-    """Persist pending changes to *path* and return the same path."""
+def _build_measured(
+    doc: "HwpxDocument", *, reset_dirty: bool
+) -> tuple[bytes, PreservationMeasurement]:
+    """Serialize + open-safety validate exactly like ``_to_bytes_raw`` and measure
+    the built archive's preservation against the pre-save part payloads.
+
+    The pre-save snapshot is captured *before* the ``serialize()`` updates are
+    applied so a per-save normalizer touching a part the editor never declared
+    dirty surfaces as an ``unexpected`` change (Safe Write Contract §2).
+    """
+
+    package = doc._package
+    # Measure against the OPEN-TIME baseline, not the current package state: a
+    # low-level ``set_part`` applied before this save already lives in
+    # ``_files``, and measuring against it would silently launder that change
+    # through a ``mode="patch"`` grade (Safe Write Contract §1, fail-closed).
+    source_members = dict(
+        getattr(package, "_opened_members", None) or package._files
+    )
+    source_infos = dict(
+        getattr(package, "_opened_zip_infos", None) or package._zip_infos
+    )
+    updates = doc._root.serialize()
+    predeclared = set(updates)
+    if updates:
+        for part_name, payload in updates.items():
+            package.set_part(part_name, payload)
+    result = package._save_to_bytes(verify_open_safety=True, mark_clean=False)
+    if not isinstance(result, bytes):
+        raise TypeError("package.save(None) must return bytes")
+    doc._run_open_safety_validation(result)
+    if reset_dirty:
+        _mark_save_clean(doc)
+    measurement = measure_save(source_members, source_infos, result, predeclared)
+    return result, measurement
+
+
+def _resolve_grade(
+    mode: Mode,
+    fallback: Fallback,
+    measurement: PreservationMeasurement,
+) -> tuple[Literal["patch", "rebuild"], bool]:
+    """Return ``(actual_mode, fallback_used)``; raise before any write when a
+    requested ``patch`` grade is unmet and ``fallback="error"`` (§1)."""
+
+    if mode == "patch" and not measurement.patch_grade_ok:
+        if fallback == "error":
+            raise PreservationDowngradeError(
+                requested_mode=mode,
+                achieved_grade=measurement.achieved_grade,
+                offending_parts=measurement.offending_parts,
+                suggestion=(
+                    "route these edits through a byte-preserving primitive "
+                    "(hwpx.patch/table_patch/body_patch) or pass fallback='rebuild'."
+                ),
+            )
+        return "rebuild", True
+    if mode == "auto":
+        return measurement.achieved_grade, False
+    if mode == "patch":
+        return "patch", False
+    return "rebuild", False
+
+
+def _verification_summary(report: "VisualCompleteReport") -> VerificationSummary:
+    """Reflect what the pipeline actually ran; never fabricate a pass (§2)."""
+
+    package: VerificationValue = "passed" if report.ok else "failed"
+    open_safety: VerificationValue = "passed" if report.open_safety.ok else "failed"
+    # Open-safety validation (which includes the reopen probe) already ran during
+    # serialize and raised on failure, so reaching here means reopen passed.
+    reopen: VerificationValue = "passed"
+    status = report.visual_complete_status
+    visual: VerificationValue = (
+        "passed"
+        if status == "verified"
+        else "failed"
+        if status == "failed"
+        else "not_performed"
+    )
+    return VerificationSummary(
+        package=package, open_safety=open_safety, reopen=reopen, visual=visual
+    )
+
+
+def _compose_mutation_report(
+    *,
+    path: str | None,
+    requested_mode: Mode,
+    actual_mode: Literal["patch", "rebuild"],
+    fallback_used: bool,
+    measurement: PreservationMeasurement,
+    report: "VisualCompleteReport",
+) -> MutationReport:
+    return MutationReport(
+        requested_mode=requested_mode,
+        actual_mode=actual_mode,
+        fallback_used=fallback_used,
+        changed_parts=measurement.changed_parts,
+        preservation=measurement.preservation,
+        verification=_verification_summary(report),
+        path=path,
+    )
+
+
+def save_to_path(
+    doc: "HwpxDocument",
+    path: str | PathLike[str],
+    *,
+    mode: Mode = "auto",
+    fallback: Fallback = "error",
+    return_report: bool = False,
+) -> str | PathLike[str] | MutationReport:
+    """Persist pending changes to *path*.
+
+    Returns *path* by default; ``return_report=True`` returns the
+    :class:`~hwpx.mutation_report.MutationReport` receipt instead. ``mode`` and
+    ``fallback`` are the Safe Write Contract grade controls — ``mode="patch"``
+    with ``fallback="error"`` raises :class:`PreservationDowngradeError` and
+    writes nothing when the save cannot keep every untouched part byte-identical.
+    """
 
     _run_pre_save_validation(doc)
-    archive_bytes = doc._to_bytes_raw(reset_dirty=False)
-    _gate_and_write(doc,
-        archive_bytes, output_path=path, source_label="document.save_to_path"
+    archive_bytes, measurement = _build_measured(doc, reset_dirty=False)
+    actual_mode, fallback_used = _resolve_grade(mode, fallback, measurement)
+    report = _gate_and_write(
+        doc, archive_bytes, output_path=path, source_label="document.save_to_path"
     )
     _mark_save_clean(doc)
+    if return_report:
+        return _compose_mutation_report(
+            path=str(path),
+            requested_mode=mode,
+            actual_mode=actual_mode,
+            fallback_used=fallback_used,
+            measurement=measurement,
+            report=report,
+        )
     return path
 
 
-def save_to_stream(doc: "HwpxDocument", stream: BinaryIO) -> BinaryIO:
-    """Persist pending changes to *stream* and return the same stream."""
+def save_to_stream(
+    doc: "HwpxDocument",
+    stream: BinaryIO,
+    *,
+    mode: Mode = "auto",
+    fallback: Fallback = "error",
+    return_report: bool = False,
+) -> BinaryIO | MutationReport:
+    """Persist pending changes to *stream*.
+
+    Returns *stream* by default; ``return_report=True`` returns the
+    :class:`~hwpx.mutation_report.MutationReport` receipt instead. See
+    :func:`save_to_path` for the ``mode``/``fallback`` grade semantics.
+    """
 
     _run_pre_save_validation(doc)
-    archive_bytes = doc._to_bytes_raw(reset_dirty=False)
-    _gate_and_write(doc,
-        archive_bytes, output_stream=stream, source_label="document.save_to_stream"
+    archive_bytes, measurement = _build_measured(doc, reset_dirty=False)
+    actual_mode, fallback_used = _resolve_grade(mode, fallback, measurement)
+    report = _gate_and_write(
+        doc, archive_bytes, output_stream=stream, source_label="document.save_to_stream"
     )
     _mark_save_clean(doc)
+    if return_report:
+        return _compose_mutation_report(
+            path=None,
+            requested_mode=mode,
+            actual_mode=actual_mode,
+            fallback_used=fallback_used,
+            measurement=measurement,
+            report=report,
+        )
     return stream
 
 
@@ -193,11 +354,26 @@ def save_report(
     return report
 
 
-def to_bytes(doc: "HwpxDocument") -> bytes:
-    """Serialize pending changes and return the HWPX archive as bytes."""
+def to_bytes(
+    doc: "HwpxDocument",
+    *,
+    mode: Mode = "auto",
+    fallback: Fallback = "error",
+) -> bytes:
+    """Serialize pending changes and return the HWPX archive as bytes.
+
+    ``mode``/``fallback`` enforce the Safe Write Contract grade the same way as
+    :func:`save_to_path`: ``mode="patch"`` with ``fallback="error"`` raises
+    :class:`PreservationDowngradeError` before returning when the archive is not
+    patch-grade. There is no ``return_report`` — the enforcement is via the typed
+    exception, so the byte return stays unchanged.
+    """
 
     _run_pre_save_validation(doc)
-    return doc._to_bytes_raw()
+    archive_bytes, measurement = _build_measured(doc, reset_dirty=False)
+    _resolve_grade(mode, fallback, measurement)
+    _mark_save_clean(doc)
+    return archive_bytes
 
 
 def _to_bytes_raw(
@@ -239,6 +415,11 @@ def _to_bytes_for_validation(doc: "HwpxDocument") -> bytes:
 def _mark_save_clean(doc: "HwpxDocument") -> None:
     doc._root.reset_dirty()
     doc._package.version_info.mark_clean()
+    # The published archive is the new preservation baseline for any further
+    # save on this document instance.
+    package = doc._package
+    package._opened_members = dict(package._files)
+    package._opened_zip_infos = dict(package._zip_infos)
 
 
 def save(

hwpx/agent/commands.py

@@ -14,9 +14,7 @@ import copy
 import hashlib
 import json
 import re
-import zipfile
 from collections.abc import Callable, Mapping, MutableMapping
-from io import BytesIO
 from pathlib import Path
 from typing import Any
 from xml.etree import ElementTree as ET
@@ -24,6 +22,7 @@ from xml.etree import ElementTree as ET
 from lxml import etree as LET  # type: ignore[reportAttributeAccessIssue]  # lxml has no complete bundled typing
 
 from hwpx.document import HwpxDocument
+from hwpx.mutation_report import member_diff_bytes
 from hwpx.oxml import HwpxOxmlTable
 from hwpx.quality import QualityPolicy, SavePipeline
 from hwpx.tools.package_validator import validate_editor_open_safety
@@ -1172,24 +1171,9 @@ def _quality_policy(value: str | Mapping[str, Any] | None) -> QualityPolicy:
 
 
 def _member_diff(before: bytes, after: bytes) -> dict[str, Any]:
-    try:
-        with zipfile.ZipFile(BytesIO(before)) as old_zip, zipfile.ZipFile(BytesIO(after)) as new_zip:
-            old_names = set(old_zip.namelist())
-            new_names = set(new_zip.namelist())
-            shared = sorted(old_names & new_names)
-            changed = [name for name in shared if old_zip.read(name) != new_zip.read(name)]
-            unchanged = len(shared) - len(changed)
-            return {
-                "ok": True,
-                "changedMembers": changed,
-                "addedMembers": sorted(new_names - old_names),
-                "removedMembers": sorted(old_names - new_names),
-                "unchangedMemberCount": unchanged,
-                "beforeMemberCount": len(old_names),
-                "afterMemberCount": len(new_names),
-            }
-    except (OSError, zipfile.BadZipFile) as exc:
-        return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
+    # 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(

hwpx/agent/model.py

@@ -15,6 +15,15 @@ from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
+from ..mutation_report import (
+    ChangedPart,
+    MutationReport,
+    PreservationCounts,
+    PreservationSummary,
+    verification_from_open_safety,
+    visual_value_from_status,
+)
+
 AGENT_NODE_SCHEMA = "hwpx.agent-node/v1"
 AGENT_COMMAND_SCHEMA = "hwpx.agent-command/v1"
 AGENT_BATCH_SCHEMA = "hwpx.agent-batch/v1"
@@ -667,6 +676,53 @@ class AgentBatchResult:
             "error": None if self.error is None else self.error.to_dict(),
         }
 
+    def as_mutation_report(self) -> MutationReport:
+        """Project this transaction result onto ``hwpx.mutation-report/v1`` (specs/032
+        §3). Additive — the fields above are untouched.
+
+        The agent write is a family-A rebuild (``document.to_bytes()``), so
+        ``actualMode`` is ``"rebuild"`` and changed parts carry no ranges (a rebuilt
+        part is re-serialized whole). Preservation and verification are read from the
+        already-measured ``verification_report`` (``bytePreservation`` = the shared
+        ``_member_diff``, ``openSafety``, ``realHancom``); layers that report never
+        measured — local ZIP records, an absent oracle — stay zero-verified /
+        ``not_performed`` rather than being promoted to a pass.
+        """
+
+        report = self.verification_report
+        byte = report.get("bytePreservation") or {}
+        changed_names = [
+            *byte.get("changedMembers", ()),
+            *byte.get("addedMembers", ()),
+            *byte.get("removedMembers", ()),
+        ]
+        changed_parts = tuple(
+            ChangedPart(path=str(name), reason="dirty-part", ranges=None)
+            for name in changed_names
+        )
+        unchanged = byte.get("unchangedMemberCount")
+        preservation = PreservationSummary(
+            untouched_part_payloads=PreservationCounts(
+                verified=unchanged if isinstance(unchanged, int) else 0, changed=0
+            ),
+            untouched_local_zip_records=PreservationCounts(verified=0, changed=0),
+            whole_package_identical=bool(byte) and not changed_names,
+        )
+        real_hancom = report.get("realHancom") or {}
+        verification = verification_from_open_safety(
+            report.get("openSafety"),
+            visual=visual_value_from_status(real_hancom.get("status")),
+        )
+        return MutationReport(
+            requested_mode="rebuild",
+            actual_mode="rebuild",
+            fallback_used=False,
+            changed_parts=changed_parts,
+            preservation=preservation,
+            verification=verification,
+            path=self.output_filename,
+        )
+
 
 def agent_contract_manifest() -> dict[str, Any]:
     """Return the deterministic, inspectable v1 contract manifest."""

hwpx/body_patch.py

@@ -35,6 +35,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from .mutation_report import MutationReport, project_byte_splice
 from .patch import (
     _finalize,
     _patch_zip_entries,
@@ -113,6 +114,21 @@ class BodyOpsResult:
             "openSafety": self.open_safety,
         }
 
+    def as_mutation_report(self, *, source: bytes | str | Path | None = None) -> MutationReport:
+        """Project this body-ops result onto ``hwpx.mutation-report/v1`` (specs/032
+        §3). Additive — the fields above are untouched. This path never renders,
+        so the visual verdict stays ``not_performed``. Pass the original *source*
+        for real ranges and a measured preservation summary.
+        """
+
+        return project_byte_splice(
+            data=self.data,
+            changed_part_names=self.changed_parts,
+            byte_identical=self.byte_identical,
+            open_safety=self.open_safety,
+            source=source,
+        )
+
 
 def _op_replace_text(xml: str, op: Mapping[str, Any]) -> tuple[str, dict[str, Any]]:
     find = str(op["find"])

hwpx/document.py

@@ -9,7 +9,17 @@ from datetime import datetime
 import logging
 
 from os import PathLike
-from typing import TYPE_CHECKING, Any, BinaryIO, Iterator, Mapping, Sequence, cast, overload
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    BinaryIO,
+    Iterator,
+    Literal,
+    Mapping,
+    Sequence,
+    cast,
+    overload,
+)
 
 
 from .oxml import (
@@ -40,6 +50,7 @@ from .opc.package import (
     HwpxPackage,
 )
 from .oxml.namespaces import register_owpml_namespaces
+from .mutation_report import Fallback, Mode, MutationReport
 from .quality import QualityPolicy, SavePipeline, VisualCompleteReport
 from .templates import blank_document_bytes
 
@@ -1682,20 +1693,92 @@ class HwpxDocument:
         )
 
 
-    def save_to_path(self, path: str | PathLike[str]) -> str | PathLike[str]:
-        """Persist pending changes to *path* and return the same path."""
+    @overload
+    def save_to_path(
+        self,
+        path: str | PathLike[str],
+        *,
+        mode: Mode = ...,
+        fallback: Fallback = ...,
+        return_report: Literal[False] = ...,
+    ) -> str | PathLike[str]: ...
+
+    @overload
+    def save_to_path(
+        self,
+        path: str | PathLike[str],
+        *,
+        mode: Mode = ...,
+        fallback: Fallback = ...,
+        return_report: Literal[True],
+    ) -> MutationReport: ...
+
+    def save_to_path(
+        self,
+        path: str | PathLike[str],
+        *,
+        mode: Mode = "auto",
+        fallback: Fallback = "error",
+        return_report: bool = False,
+    ) -> str | PathLike[str] | MutationReport:
+        """Persist pending changes to *path* and return the same path.
+
+        ``return_report=True`` returns the Safe Write Contract
+        :class:`~hwpx.mutation_report.MutationReport` instead. ``mode="patch"``
+        with ``fallback="error"`` raises
+        :class:`~hwpx.mutation_report.PreservationDowngradeError` and writes
+        nothing when an untouched part would not stay byte-identical.
+        """
 
         return _persistence.save_to_path(
             self,
             path=path,
+            mode=mode,
+            fallback=fallback,
+            return_report=return_report,
         )
 
-    def save_to_stream(self, stream: BinaryIO) -> BinaryIO:
-        """Persist pending changes to *stream* and return the same stream."""
+    @overload
+    def save_to_stream(
+        self,
+        stream: BinaryIO,
+        *,
+        mode: Mode = ...,
+        fallback: Fallback = ...,
+        return_report: Literal[False] = ...,
+    ) -> BinaryIO: ...
+
+    @overload
+    def save_to_stream(
+        self,
+        stream: BinaryIO,
+        *,
+        mode: Mode = ...,
+        fallback: Fallback = ...,
+        return_report: Literal[True],
+    ) -> MutationReport: ...
+
+    def save_to_stream(
+        self,
+        stream: BinaryIO,
+        *,
+        mode: Mode = "auto",
+        fallback: Fallback = "error",
+        return_report: bool = False,
+    ) -> BinaryIO | MutationReport:
+        """Persist pending changes to *stream* and return the same stream.
+
+        ``return_report=True`` returns the Safe Write Contract
+        :class:`~hwpx.mutation_report.MutationReport` instead. See
+        :meth:`save_to_path` for the ``mode``/``fallback`` grade semantics.
+        """
 
         return _persistence.save_to_stream(
             self,
             stream=stream,
+            mode=mode,
+            fallback=fallback,
+            return_report=return_report,
         )
 
     def save_report(
@@ -1730,10 +1813,21 @@ class HwpxDocument:
             ledger=ledger,
         )
 
-    def to_bytes(self) -> bytes:
-        """Serialize pending changes and return the HWPX archive as bytes."""
+    def to_bytes(
+        self,
+        *,
+        mode: Mode = "auto",
+        fallback: Fallback = "error",
+    ) -> bytes:
+        """Serialize pending changes and return the HWPX archive as bytes.
+
+        ``mode="patch"`` with ``fallback="error"`` raises
+        :class:`~hwpx.mutation_report.PreservationDowngradeError` before
+        returning when the archive is not patch-grade; the byte return itself is
+        unchanged.
+        """
 
-        return _persistence.to_bytes(self)
+        return _persistence.to_bytes(self, mode=mode, fallback=fallback)
 
     def _to_bytes_raw(
         self,