python-hwpx 5.4.0__tar.gz → 5.6.0__tar.gz

{python_hwpx-5.4.0/src/python_hwpx.egg-info → python_hwpx-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.4.0
+Version: 5.6.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-5.4.0 → python_hwpx-5.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.4.0"
+version = "5.6.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -109,6 +109,7 @@ packages = [
     "hwpx.layout",
     "hwpx.opc",
     "hwpx.oxml",
+    "hwpx.plan",
     "hwpx.quality",
     "hwpx.tools",
     "hwpx.tools._schemas",
@@ -125,7 +126,7 @@ packages = [
 [tool.setuptools.package-data]
 "hwpx" = ["py.typed"]
 "hwpx.tools" = ["_schemas/*.xsd"]
-"hwpx.data" = ["Skeleton.hwpx"]
+"hwpx.data" = ["Skeleton.hwpx", "contract_docs/*.md"]
 
 [tool.pytest.ini_options]
 # scripts/ carries repository QA harnesses that are not library surface — the
@@ -145,6 +146,12 @@ files = [
     "src/hwpx/document.py",
     "src/hwpx/errors.py",
     "src/hwpx/mutation_report.py",
+    "src/hwpx/capabilities.py",
+    "src/hwpx/plan/__init__.py",
+    "src/hwpx/plan/_model.py",
+    "src/hwpx/plan/_validate.py",
+    "src/hwpx/plan/_execute.py",
+    "src/hwpx/plan/_schema.py",
     "src/hwpx/equation/__init__.py",
     "src/hwpx/equation/tokens.py",
     "src/hwpx/equation/eqedit.py",
@@ -200,6 +207,12 @@ include = [
     "src/hwpx/document.py",
     "src/hwpx/errors.py",
     "src/hwpx/mutation_report.py",
+    "src/hwpx/capabilities.py",
+    "src/hwpx/plan/__init__.py",
+    "src/hwpx/plan/_model.py",
+    "src/hwpx/plan/_validate.py",
+    "src/hwpx/plan/_execute.py",
+    "src/hwpx/plan/_schema.py",
     "src/hwpx/equation/__init__.py",
     "src/hwpx/equation/tokens.py",
     "src/hwpx/equation/eqedit.py",

{python_hwpx-5.4.0 → python_hwpx-5.6.0}/src/hwpx/__init__.py

@@ -52,6 +52,18 @@ _EXPERIMENTAL_EXPORTS = {
     "UnsupportedLatexError": "hwpx.equation.authoring",
     "estimate_equation_size": "hwpx.equation.authoring",
     "latex_to_eqedit": "hwpx.equation.authoring",
+    # 편집 계획 실행기(5.6.0 신규, 선언적 다단 편집 -> 원자 실행). 계약 유동.
+    "EditPlan": "hwpx.plan",
+    "PlanReport": "hwpx.plan",
+    "PlanValidationError": "hwpx.plan",
+    "apply_edit_plan": "hwpx.plan",
+    "validate_edit_plan": "hwpx.plan",
+    # 기계가독 자기서술(5.6.0 신규, 드리프트 가드 포함). 계약 유동.
+    # 함수명은 describe_capabilities — 모듈 hwpx.capabilities와 이름이 같으면
+    # 서브모듈 바인딩이 lazy 알리아스를 그림자로 가려 경고 계약이 깨진다.
+    "describe_capabilities": "hwpx.capabilities",
+    "contract_document": "hwpx.capabilities",
+    "contract_json_schema": "hwpx.capabilities",
 }
 
 # Emptied in 5.0. The 4.x notice on these names said they would go in the next

python_hwpx-5.6.0/src/hwpx/capabilities.py

@@ -0,0 +1,466 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``hwpx.capabilities`` — 기계가독 자기서술 (experimental, 5.6.0 신규).
+
+동기(실측 드리프트 사례): 사람 손으로 갱신하는 자기서술 문서는 릴리스 트레인
+하루 만에도 실표면과 드리프트한다. 이 모듈이 단일 진실 원천이고, 드리프트
+가드 테스트가 다음 세 방향을 강제한다:
+
+1. 여기 등재된 진입점은 전부 실제로 import 가능해야 한다.
+2. ``editPlanOps``는 :data:`hwpx.plan.PLAN_OPS`·실행 디스패치·edit-plan JSON
+   Schema enum과 일치해야 한다.
+3. :data:`_CAPABILITY_AREAS`의 매트릭스 행 제목은 ``docs/support-matrix.md``
+   표의 행 제목과 집합 일치해야 한다.
+
+**core는 환경 변수를 읽지 않는다** — 렌더 오라클 가용성은 여기 없다(자기서술은
+``renderOracle.bundled="none"``으로 그 사실 자체를 말한다). 오라클 탐지·실행은
+automation 계층(python-hwpx-automation)이 보고한다.
+"""
+
+from __future__ import annotations
+
+import platform
+from pathlib import Path
+from typing import Any
+
+from .errors import HwpxError
+
+CAPABILITIES_SCHEMA = "hwpx.capabilities/v1"
+
+_DIST_NAME = "python-hwpx"
+
+#: extras 이름 → 그 extra가 끄는 런타임 모듈들. ``visual``은 5.0부터 의도적으로
+#: 빈 extra(설치 호환 유지용)라 백킹 모듈이 없고, 프로브는 공허하게 참이다.
+_EXTRA_MODULES: dict[str, tuple[str, ...]] = {
+    "visual": (),
+    "xlsx": ("openpyxl",),
+    "preview": ("latex2mathml",),
+}
+
+#: 능력 영역 레지스트리. ``matrix_row``는 ``docs/support-matrix.md`` 표 1열
+#: 제목과 **정확히** 일치해야 한다(가드 테스트가 집합 대조). ``entry_points``는
+#: ``"모듈:이름"`` — 전부 import 가능해야 한다(가드 테스트가 해석).
+_CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
+    {
+        "area": "paragraph-table-authoring",
+        "matrix_row": "문단·표 저작/편집",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "table-structure",
+        "matrix_row": "표 구조 변경(행·열·표 삭제/삽입, 열 오토핏)",
+        "entry_points": ("hwpx.table_patch:apply_table_ops",),
+    },
+    {
+        "area": "table-create",
+        "matrix_row": "표 생성(병합·중첩 포함)",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "form-fill",
+        "matrix_row": "양식 채움(byte-splice)",
+        "entry_points": (
+            "hwpx.patch:paragraph_patch",
+            "hwpx.table_patch:fill_cells",
+            "hwpx.body_patch:apply_body_ops",
+        ),
+    },
+    {
+        "area": "edit-plan",
+        "matrix_row": "편집 계획 실행(edit plan)",
+        "entry_points": (
+            "hwpx.plan:apply_edit_plan",
+            "hwpx.plan:validate_edit_plan",
+        ),
+    },
+    {
+        "area": "shape-authoring",
+        "matrix_row": "도형 저작(선·사각형·타원)",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "shape-escape-hatch",
+        "matrix_row": "저수준 도형·컨트롤 탈출구",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "curve-objects",
+        "matrix_row": "arc·polygon·curve·connectLine",
+        "entry_points": (),
+    },
+    {
+        "area": "picture",
+        "matrix_row": "그림 삽입/치환",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "chart",
+        "matrix_row": "차트",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "equation",
+        "matrix_row": "수식",
+        "entry_points": ("hwpx.equation.authoring:latex_to_eqedit",),
+    },
+    {
+        "area": "redline",
+        "matrix_row": "변경추적(redline)",
+        "entry_points": ("hwpx.tools.redline:verify_redline",),
+    },
+    {
+        "area": "memo",
+        "matrix_row": "메모(코멘트)",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "footnote-endnote",
+        "matrix_row": "각주/미주",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+    {
+        "area": "toc-crossref",
+        "matrix_row": "네이티브 목차(TOC)/상호참조",
+        "entry_points": ("hwpx.tools.toc_author:add_native_toc",),
+    },
+    {
+        "area": "encrypted-hwpx",
+        "matrix_row": "암호화 HWPX",
+        "entry_points": (),
+    },
+    {
+        "area": "hwp5-binary",
+        "matrix_row": "HWP 5.x 바이너리",
+        "entry_points": (),
+    },
+    {
+        "area": "form-field-create",
+        "matrix_row": "누름틀(form field) 생성",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+    },
+)
+
+#: 패키지에 동봉되는 계약 문서 이름 → 파일. MCP resources 표면의 원천.
+_CONTRACT_DOCS: dict[str, str] = {
+    "support-matrix": "support-matrix.md",
+    "recipes-traversal": "recipes-traversal.md",
+    "mutation-semantics": "mutation-semantics.md",
+    "known-traps": "known-traps.md",
+}
+
+_CONTRACT_DOCS_DIR = Path(__file__).resolve().parent / "data" / "contract_docs"
+
+
+def _extra_installed(extra: str) -> bool:
+    """extra 설치 여부 — 함수 스코프 **정적 import** try/except 프로브.
+
+    core의 importlib 표면은 boundary ratchet상 ``from importlib import
+    resources`` 한 형태뿐이라 동적 프로브(find_spec/import_module)를 쓰지
+    않는다. 닫힌 extras 집합이므로 하우스 패턴(mail_merge의 지연 import)과
+    같은 정적 guarded import면 충분하다.
+    """
+
+    if extra == "xlsx":
+        try:
+            import openpyxl  # noqa: F401
+        except Exception:
+            return False
+        return True
+    if extra == "preview":
+        from .equation.mathml import latex2mathml_available
+
+        return latex2mathml_available()
+    # visual: 5.0부터 의도적 빈 extra(설치 호환 유지) — 공허하게 참.
+    return True
+
+
+def _package_version() -> str:
+    from . import __version__
+
+    return str(__version__)
+
+
+# 진입점 실해석(import_module)은 런타임에 없다 — core의 동적 import 능력은
+# __init__의 핀된 lazy 로더뿐(boundary ratchet). 레지스트리 진입점이 전부
+# 해석되는지는 tests/test_capabilities_surface.py의 드리프트 가드가 실측한다.
+
+
+def describe_capabilities() -> dict[str, Any]:
+    """설치된 core의 기계가독 자기서술 — ``hwpx.capabilities/v1``.
+
+    전부 실측이다: 버전은 배포 메타데이터, extras는 import 프로브, 표면 목록은
+    라이브 ``__all__``, op 어휘는 실행기 디스패치와 같은 표. 렌더 오라클은
+    core에 없다는 사실 자체를 보고한다(측정 없는 가용성 주장 금지).
+    """
+
+    from . import __all__ as stable_names
+    from .experimental import __all__ as experimental_names
+    from .plan import PLAN_OPS
+
+    return {
+        "schemaVersion": CAPABILITIES_SCHEMA,
+        "package": {"name": _DIST_NAME, "version": _package_version()},
+        "python": platform.python_version(),
+        "extras": {name: _extra_installed(name) for name in _EXTRA_MODULES},
+        "renderOracle": {
+            "bundled": "none",
+            "note": (
+                "core는 렌더 백엔드를 동봉하지 않습니다(RenderBackend 주입 seam). "
+                "실한컴 오라클 탐지·실행과 그 가용성 보고는 python-hwpx-automation"
+                "이 소유합니다."
+            ),
+        },
+        "editPlanOps": sorted(PLAN_OPS),
+        "schemas": sorted(_SCHEMA_BUILDERS),
+        "surfaces": {
+            "stable": sorted(stable_names),
+            "experimental": sorted(experimental_names),
+        },
+        "features": [
+            {
+                "area": row["area"],
+                "matrixRow": row["matrix_row"],
+                "entryPoints": list(row["entry_points"]),
+            }
+            for row in _CAPABILITY_AREAS
+        ],
+        "contractDocuments": sorted(_CONTRACT_DOCS),
+    }
+
+
+def contract_document(name: str) -> str:
+    """패키지에 동봉된 계약 문서(markdown 원문)를 돌려준다.
+
+    이름 어휘는 ``describe_capabilities()["contractDocuments"]``와 같다. 미지 이름은
+    typed 거부(fail-closed).
+    """
+
+    filename = _CONTRACT_DOCS.get(name)
+    if filename is None:
+        raise HwpxError(
+            f"미지 계약 문서 '{name}'입니다.",
+            code="unknown-contract-document",
+            suggestion=f"가능한 이름: {', '.join(sorted(_CONTRACT_DOCS))}",
+        )
+    path = _CONTRACT_DOCS_DIR / filename
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise HwpxError(
+            f"계약 문서가 패키지에 없습니다: {name}",
+            code="contract-document-missing",
+            context={"path": str(path)},
+            suggestion=(
+                "개발 체크아웃이라면 scripts/sync_contract_docs.py를 실행해 "
+                "docs/ 원본을 data/contract_docs/로 동기화하세요."
+            ),
+        ) from exc
+
+
+def _mutation_report_json_schema() -> dict[str, Any]:
+    """``hwpx.mutation-report/v1``의 JSON Schema.
+
+    형태의 진실 원천은 :mod:`hwpx.mutation_report`의 ``to_dict()``들이다 —
+    테스트가 실제 리포트 사영을 이 스키마로 검증해 두 표현의 드리프트를 막는다.
+    최상위 필수 키 9개는 automation의 동결 계약(FROZEN_MUTATION_REPORT_KEYS)과
+    같다.
+    """
+
+    verification_value = {"enum": ["passed", "failed", "not_performed"]}
+    counts = {
+        "type": "object",
+        "required": ["verified", "changed"],
+        "properties": {
+            "verified": {"type": "integer", "minimum": 0},
+            "changed": {"type": "integer", "minimum": 0},
+        },
+    }
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": "https://airmang.github.io/python-hwpx/schemas/mutation-report-v1.json",
+        "title": "hwpx.mutation-report/v1",
+        "type": "object",
+        "required": [
+            "schemaVersion",
+            "ok",
+            "path",
+            "requestedMode",
+            "actualMode",
+            "fallbackUsed",
+            "changedParts",
+            "preservation",
+            "verification",
+        ],
+        "properties": {
+            "schemaVersion": {"const": "hwpx.mutation-report/v1"},
+            "ok": {"type": "boolean"},
+            "path": {"type": ["string", "null"]},
+            "requestedMode": {"enum": ["patch", "rebuild", "auto"]},
+            "actualMode": {"enum": ["patch", "rebuild"]},
+            "fallbackUsed": {"type": "boolean"},
+            "changedParts": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": ["path", "reason", "ranges"],
+                    "properties": {
+                        "path": {"type": "string"},
+                        "reason": {"enum": ["dirty-part", "unexpected"]},
+                        "ranges": {
+                            "type": ["array", "null"],
+                            "items": {
+                                "type": "object",
+                                "required": ["start", "end", "coordinateSpace"],
+                                "properties": {
+                                    "start": {"type": "integer", "minimum": 0},
+                                    "end": {"type": "integer", "minimum": 0},
+                                    "coordinateSpace": {
+                                        "const": "uncompressed-part-bytes"
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            "preservation": {
+                "type": "object",
+                "required": [
+                    "untouchedPartPayloads",
+                    "untouchedLocalZipRecords",
+                    "wholePackageIdentical",
+                ],
+                "properties": {
+                    "untouchedPartPayloads": counts,
+                    "untouchedLocalZipRecords": counts,
+                    "wholePackageIdentical": {"type": "boolean"},
+                },
+            },
+            "verification": {
+                "type": "object",
+                "required": ["package", "openSafety", "reopen", "visual"],
+                "properties": {
+                    "package": verification_value,
+                    "openSafety": verification_value,
+                    "reopen": verification_value,
+                    "visual": verification_value,
+                },
+            },
+        },
+    }
+
+
+def _capabilities_json_schema() -> dict[str, Any]:
+    """``hwpx.capabilities/v1``의 JSON Schema."""
+
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": "https://airmang.github.io/python-hwpx/schemas/capabilities-v1.json",
+        "title": CAPABILITIES_SCHEMA,
+        "type": "object",
+        "required": [
+            "schemaVersion",
+            "package",
+            "python",
+            "extras",
+            "renderOracle",
+            "editPlanOps",
+            "schemas",
+            "surfaces",
+            "features",
+            "contractDocuments",
+        ],
+        "properties": {
+            "schemaVersion": {"const": CAPABILITIES_SCHEMA},
+            "package": {
+                "type": "object",
+                "required": ["name", "version"],
+                "properties": {
+                    "name": {"const": _DIST_NAME},
+                    "version": {"type": "string"},
+                },
+            },
+            "python": {"type": "string"},
+            "extras": {
+                "type": "object",
+                "additionalProperties": {"type": "boolean"},
+            },
+            "renderOracle": {
+                "type": "object",
+                "required": ["bundled", "note"],
+                "properties": {
+                    "bundled": {"const": "none"},
+                    "note": {"type": "string"},
+                },
+            },
+            "editPlanOps": {"type": "array", "items": {"type": "string"}},
+            "schemas": {"type": "array", "items": {"type": "string"}},
+            "surfaces": {
+                "type": "object",
+                "required": ["stable", "experimental"],
+                "properties": {
+                    "stable": {"type": "array", "items": {"type": "string"}},
+                    "experimental": {"type": "array", "items": {"type": "string"}},
+                },
+            },
+            "features": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": ["area", "matrixRow", "entryPoints"],
+                    "properties": {
+                        "area": {"type": "string"},
+                        "matrixRow": {"type": "string"},
+                        "entryPoints": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                        },
+                    },
+                },
+            },
+            "contractDocuments": {"type": "array", "items": {"type": "string"}},
+        },
+    }
+
+
+def _edit_plan_schema() -> dict[str, Any]:
+    from .plan import edit_plan_json_schema
+
+    return edit_plan_json_schema()
+
+
+def _plan_report_schema() -> dict[str, Any]:
+    from .plan import plan_report_json_schema
+
+    return plan_report_json_schema()
+
+
+_SCHEMA_BUILDERS: dict[str, Any] = {
+    "hwpx.edit-plan/v1": _edit_plan_schema,
+    "hwpx.plan-report/v1": _plan_report_schema,
+    "hwpx.mutation-report/v1": _mutation_report_json_schema,
+    "hwpx.capabilities/v1": _capabilities_json_schema,
+}
+
+
+def contract_json_schema(name: str) -> dict[str, Any]:
+    """계약 스키마를 이름으로 돌려준다(라이브 빌드 — 파일 박제 없음).
+
+    이름 어휘는 ``describe_capabilities()["schemas"]``와 같다. 미지 이름은 typed 거부.
+    """
+
+    builder = _SCHEMA_BUILDERS.get(name)
+    if builder is None:
+        raise HwpxError(
+            f"미지 계약 스키마 '{name}'입니다.",
+            code="unknown-contract-schema",
+            suggestion=f"가능한 이름: {', '.join(sorted(_SCHEMA_BUILDERS))}",
+        )
+    return builder()
+
+
+__all__ = [
+    "CAPABILITIES_SCHEMA",
+    "describe_capabilities",
+    "contract_document",
+    "contract_json_schema",
+]

python_hwpx-5.6.0/src/hwpx/data/contract_docs/known-traps.md

@@ -0,0 +1,68 @@
+# 알려진 함정 사전 (Known Traps)
+
+에이전트·자동화 코드가 python-hwpx로 문서를 다룰 때 실제로 밟아 본 함정들의
+사전이다. 각 항목은 "무엇이, 왜, 어떻게 피하나"만 말한다. 이 문서는 패키지에
+동봉되어 `hwpx.capabilities.contract_document("known-traps")`와 MCP 리소스로도
+제공된다.
+
+## 편집·저장
+
+- **바이트-스플라이스 op의 `output_path`는 게이트 실패에도 쓴다.**
+  `paragraph_patch`·`fill_cells`·`apply_table_ops`·`apply_body_ops` 계열은
+  결과가 skip·불안전이어도 `output_path`를 주면 파일을 쓴다(전 op 스킵 시
+  원본 바이트 그대로 기록). 합성 실행이 필요하면 `output_path` 없이 부르고
+  쓰기를 직접 소유하거나, 처음부터 `hwpx.plan.apply_edit_plan`(all-or-nothing
+  원자 실행)을 쓰라.
+- **결과 `ok`는 "스킵 0 + open-safety 통과"다.** 스킵은 부분 적용이 아니라
+  "그 항목은 건드리지 않았다"는 뜻이다 — `ok=False`인데 산출물을 채택하면
+  무음 부분 적용이 된다.
+- **`SavePipeline`의 `quality=None` 기본값은 strict다.** 내부 호출은 전부
+  `QualityPolicy.transparent()`를 명시한다. 파이프라인을 직접 부를 때 기본값에
+  의존하면 의도보다 강한 게이트로 거부될 수 있다.
+- **`apply_table_ops`의 `delete_table` 여러 건은 역순으로.** 표 삭제는 후행
+  `table_index`를 시프트한다 — 내림차순으로 배열하라(`hwpx.plan`의 정적
+  린트가 위반을 경고한다).
+- **`apply_body_ops` 인덱스는 실행 시점 문서 순서다.** 문단 삭제/삽입 op를
+  섞으면 뒤 op의 인덱스가 밀린다 — 인덱스 기반 op는 문서 끝에서 앞으로.
+- **저수준 `add_shape`/`add_control`은 OWPML 필수 하위 요소를 만들지 않는다.**
+  그대로 저장하면 실한컴이 문서를 거부한다(경고 `UserWarning` 하나가 유일한
+  신호). 도형은 전용 `add_line`/`add_rectangle`/`add_ellipse`를 쓰라.
+- **텍스트를 갈아 끼우면 lineseg 캐시가 무효다.** 스플라이스 계열은 편집 문단의
+  `<hp:linesegarray>`를 스스로 떨군다(안 떨구면 한컴이 옛 줄 자리에 새 글자를
+  그려 겹침이 생긴다). 직접 XML을 만질 때도 같은 규칙을 지켜야 한다.
+
+## 검증·오라클
+
+- **렌더 검증 없이 "렌더된다"고 주장하지 말 것.** core는 렌더 백엔드를 동봉하지
+  않는다(`RenderBackend` 주입 seam, 기본은 Unavailable). `render_checked=False,
+  ok=True`는 "구조만 봤다"는 정직 degrade이지 시각 합격이 아니다. 시각 합격이
+  필요하면 `require=True`(fail-closed) + 실한컴 오라클이 있는 환경에서.
+- **`visual_complete_status="unverified"`는 합격이 아니다.** 렌더가 돌지 않은
+  것이며, 어떤 경로도 이를 pass로 승격하지 않는다.
+- **기본 테스트 스위트에서 라이브 한컴 렌더를 켜지 말 것.** 오라클은 환경
+  의존이라 flake의 근원이다 — 라이브 렌더는 opt-in 게이트로만.
+
+## 문서 구조
+
+- **네이티브 목차는 `dirty="1"`이 재계산 트리거다.** 목차 삽입/문서 변경 후
+  `mark_toc_dirty`를 잊으면 한컴이 옛 페이지 번호를 그대로 보여준다. dirty
+  재생성 직후 같은 세션에서 export하면 한컴이 크래시할 수 있다(refresh와
+  render는 세션 분리).
+- **본문 문단이 스타일 0(바탕글)이면 목차에 수집될 수 있다.** 한컴 목차 수집은
+  스타일 기반이다 — 본문은 본문 스타일, 제목은 개요 스타일로.
+- **메모 필드는 무음 수용 캐비앗이 있다.** `attach_memo_field`가 앵커를 못
+  찾아도 조용히 넘어가는 경로가 있다(recipes의 mutation-semantics 표 참조) —
+  결과 리포트의 실측 필드를 확인하라.
+- **암호화 HWPX·HWP5 바이너리는 열리지 않는 게 정상이다.** 각각 파싱 예외·
+  `BadZipFile`로 fail-closed 거부한다. 우회 API는 없다.
+
+## 계획 실행기(hwpx.plan) 자체의 정직 범위
+
+- **저널은 재개(resume) 계약이 아니다.** 진단용 JSONL이다. 부분 재실행은
+  지원하지 않는다 — 실패하면 계획을 고쳐 처음부터 다시 실행하라(실패 시 파일
+  무접촉이므로 안전하다).
+- **`journalPath`는 실패 시에도 쓰이는 유일한 파일 표면이다.** 문서 파일의
+  무접촉 보장과 별개다(원하지 않으면 지정하지 말 것).
+- **step `args`의 중첩 op 어휘는 스키마가 깊게 검증하지 않는다.** 실행-시
+  해당 op의 fail-closed 검증이 진실 원천이다 — dry_run으로 전체 체인을 미리
+  실행해 transcript를 확인하는 것이 가장 확실한 선검증이다.

python_hwpx-5.6.0/src/hwpx/data/contract_docs/mutation-semantics.md

@@ -0,0 +1,59 @@
+# 편집 의미론 — 무엇이 돌아오고, 어떻게 실패하고, 다시 실행하면 어떻게 되나
+
+stable 편집 표면의 계약을 한 곳에 모았다. 아래 표의 실패 모드와 재실행
+성질은 전부 이 저장소의 테스트·실측으로 확인된 동작이다. 보존 등급 어휘는
+[안전한 쓰기 계약](safe-write-contract.md), stable/experimental 구분은
+[stable API](stable-api.md)를 따른다.
+
+> **Python 블록 판정:** [실행 분류 ledger](python-example-ledger.json)가 이
+> current manual의 모든 Python 블록을 동결합니다. 이 문서의 블록은 앞 문맥의
+> `document`가 필요한 조각입니다.
+
+## 핵심 편집 호출 계약
+
+| 호출 | 반환 | 대표 실패 모드 | 다시 실행하면 |
+|---|---|---|---|
+| `add_paragraph(text)` | `HwpxOxmlParagraph` | 사실상 없음 | 문단이 하나 더 추가된다(append, 비멱등) |
+| `remove_paragraph(p)` | `None` | 섹션의 마지막 단락 삭제 시 `ValueError` | 이미 제거된 문단이면 조용히 무시된다(무해) |
+| `add_table(rows, cols)` | `HwpxOxmlTable` | 사실상 없음 | 표가 하나 더 추가된다(비멱등) |
+| `table.set_cell_text(r, c, text)` | `FitResult \| None` | 범위 밖 좌표는 `IndexError` (`exceed table bounds`) | 같은 값이면 결과 동일(수렴) |
+| `replace_text_in_runs(search, repl)` | `int` (치환 수) | 빈 `search`는 `ValueError` | 치환할 것이 없으면 `0` — 1회차 후 수렴 |
+| `add_memo_with_anchor(...)` | `(memo, paragraph, field_id)` 튜플 | 아래 캐비앗 참고 | 메모가 하나 더 붙는다(비멱등) |
+| `add_footnote(text, paragraph)` | `HwpxOxmlNote` | 사실상 없음 | 각주가 하나 더 붙는다(비멱등) |
+
+"사실상 없음"은 정상 인자에서 실패 경로가 없다는 뜻이다 — 타입이 어긋난
+인자는 여느 파이썬 API처럼 `TypeError` 계열로 즉시 드러난다.
+
+## 저장 의미론
+
+```python
+report = document.save_to_path("out.hwpx", return_report=True)
+print(report.actual_mode)
+```
+
+- `save_to_path()`는 원자적이다: 임시 파일에 쓴 뒤 rename하고, editor-open
+  안전 검증을 통과한 결과만 대상 경로를 교체한다.
+- 요청한 보존 등급(`mode="patch"` 등)을 지킬 수 없으면
+  `PreservationDowngradeError`로 실패하고 **아무것도 쓰지 않는다**
+  (fail-closed). 자동 다운그레이드는 없다.
+- `return_report=True`는 `MutationReport`를 돌려준다 — 실제 저장 모드,
+  손대지 않은 파트의 바이트 보존 검증 결과까지. 스키마와 전체 규칙은
+  [안전한 쓰기 계약](safe-write-contract.md).
+- **직렬화는 결정론적이다**: 같은 문서 상태에서 `to_bytes()`를 두 번 부르면
+  바이트가 동일하다(실측). diff·해시 기반 파이프라인에 안전하다.
+
+## 알아둘 캐비앗 (정직 고지)
+
+- `add_memo_with_anchor(memo_shape_id_ref=...)`는 참조가 실재하는 메모
+  모양인지 **검증하지 않고 조용히 수용한다**. 존재하지 않는 ID를 넣으면
+  저장은 되지만 편집기 표시가 어긋날 수 있다. `document.memo_shapes`로
+  실재 ID를 확인하고 쓰는 것을 권장한다.
+- `add_*` 계열은 전부 append 의미론이다. "없으면 추가"가 필요하면 먼저
+  {doc}`recipes-traversal`의 순회로 존재 여부를 확인하라.
+- 편집은 저장 전까지 메모리에만 있다. 저장 경로가 곧 커밋이다.
+
+## 다음 단계
+
+- 문서에서 원하는 것을 꺼내는 법 → {doc}`recipes-traversal`
+- 보존 등급·영수증 스키마 → [안전한 쓰기 계약](safe-write-contract.md)
+- 표면 안정성 구분(stable/experimental) → [stable API](stable-api.md)