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

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,
@@ -85,6 +89,10 @@ from .ingest import (
     HwpxMarkdownConverter,
     UnsupportedDocumentFormat,
 )
+from .mutation_report import (
+    MutationReport,
+    PreservationDowngradeError,
+)
 from .patch import (
     BytePreservingPatchResult,
     ParagraphTextPatch,
@@ -146,6 +154,8 @@ __all__ = [
     "ParagraphInfo",
     "PackageValidationReport",
     "BytePreservingPatchResult",
+    "MutationReport",
+    "PreservationDowngradeError",
     "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",
@@ -200,6 +210,8 @@ __all__ = [
     "validate_package",
     "paragraph_patch",
     "render_layout_preview",
+    "render_document_viewer",
+    "DocumentViewer",
     "register_template",
     "table_compute",
 ]

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/_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