python-hwpx 5.7.0__tar.gz → 5.8.0__tar.gz

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/NOTICE

@@ -58,6 +58,14 @@ neolord0/hwpxlib (https://github.com/neolord0/hwpxlib), licensed Apache-2.0.
 Only sample DATA files are vendored; no hwpxlib source code or structure is
 copied (clean-room). Pinned ref is recorded in manifest.json.
 
+## Hancom file-format specification attribution
+
+Parts of this project were developed with reference to the publicly
+released Hancom file-format documentation (HWP 5.0 / HWPML) and the
+public OWPML schema. As required by that documentation:
+
+“본 제품은 한글과컴퓨터의 ᄒᆞᆫ글 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.”
+
 ────────────────────────────────────────
 DISCLAIMER — HWPX Format
 

{python_hwpx-5.7.0/src/python_hwpx.egg-info → python_hwpx-5.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.7.0
+Version: 5.8.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -158,10 +158,15 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 실측으로 말합니다
 
-만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
-그대로 공개합니다:
+만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
+스택과 날짜를 병기합니다:
 
-- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
+  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
+  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
+  (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
 - **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
 - 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/README.md

@@ -107,10 +107,15 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 실측으로 말합니다
 
-만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
-그대로 공개합니다:
-
-- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
+스택과 날짜를 병기합니다:
+
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
+  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
+  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
+  (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
 - **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
 - 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.7.0"
+version = "5.8.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/capabilities.py

@@ -8,8 +8,17 @@
 1. 여기 등재된 진입점은 전부 실제로 import 가능해야 한다.
 2. ``editPlanOps``는 :data:`hwpx.plan.PLAN_OPS`·실행 디스패치·edit-plan JSON
    Schema enum과 일치해야 한다.
-3. :data:`_CAPABILITY_AREAS`의 매트릭스 행 제목은 ``docs/support-matrix.md``
-   표의 행 제목과 집합 일치해야 한다.
+3. :data:`_CAPABILITY_AREAS`의 ``authoring_methods``는 라이브
+   ``HwpxDocument``의 ``add_*`` 전수와 정확히 일치해야 한다 — **레지스트리를
+   코드에 대조하는 방향**이다.
+4. 매트릭스 행 제목은 ``docs/support-matrix.md`` 표의 행 제목과 집합 일치해야
+   한다.
+
+3번이 있는 이유: 4번만으로는 부족하다. 문서 둘이 서로 맞는다는 사실은 코드에
+대해 아무것도 말해주지 않으므로, **양쪽에 다 없는** 능력은 통과한다. 실제로
+``add_check_box``가 5.7.0에서 실한컴 수용 게이트까지 통과해 출하됐는데
+레지스트리에도 매트릭스에도 없었다 — 이 부류의 드리프트를 "구조적으로
+막는다"고 선언한 바로 다음 릴리스에서다. 코드에 대조해야 잡힌다.
 
 **core는 환경 변수를 읽지 않는다** — 렌더 오라클 가용성은 여기 없다(자기서술은
 ``renderOracle.bundled="none"``으로 그 사실 자체를 말한다). 오라클 탐지·실행은
@@ -39,21 +48,39 @@ _EXTRA_MODULES: dict[str, tuple[str, ...]] = {
 #: 능력 영역 레지스트리. ``matrix_row``는 ``docs/support-matrix.md`` 표 1열
 #: 제목과 **정확히** 일치해야 한다(가드 테스트가 집합 대조). ``entry_points``는
 #: ``"모듈:이름"`` — 전부 import 가능해야 한다(가드 테스트가 해석).
+#: Every ``HwpxDocument.add_*`` method must be claimed by exactly one area.
+#:
+#: ``entry_points`` names modules, which is too coarse to notice a new
+#: authoring method: ten areas all point at ``hwpx.document:HwpxDocument``. So
+#: ``authoring_methods`` names the methods, and the guard in
+#: ``tests/test_capabilities_surface.py`` compares this registry against the
+#: live class.
+#:
+#: Why the guard runs in that direction: the previous guard compared the
+#: registry's row titles against the row titles in ``docs/support-matrix.md``.
+#: Two documents agreeing with each other says nothing about the code, so a
+#: capability missing from *both* passed. ``add_check_box`` shipped in 5.7.0
+#: with a real-Hancom acceptance gate and appeared in neither, one release
+#: after the changelog announced that this class of drift was now structurally
+#: blocked. Comparing against the class is the direction that can catch it.
 _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
     {
         "area": "paragraph-table-authoring",
         "matrix_row": "문단·표 저작/편집",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_paragraph", "add_section"),
     },
     {
         "area": "table-structure",
         "matrix_row": "표 구조 변경(행·열·표 삭제/삽입, 열 오토핏)",
         "entry_points": ("hwpx.table_patch:apply_table_ops",),
+        "authoring_methods": (),
     },
     {
         "area": "table-create",
         "matrix_row": "표 생성(병합·중첩 포함)",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_table",),
     },
     {
         "area": "form-fill",
@@ -63,6 +90,7 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
             "hwpx.table_patch:fill_cells",
             "hwpx.body_patch:apply_body_ops",
         ),
+        "authoring_methods": (),
     },
     {
         "area": "edit-plan",
@@ -71,71 +99,91 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
             "hwpx.plan:apply_edit_plan",
             "hwpx.plan:validate_edit_plan",
         ),
+        "authoring_methods": (),
     },
     {
         "area": "shape-authoring",
         "matrix_row": "도형 저작(선·사각형·타원)",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_line", "add_rectangle", "add_ellipse"),
     },
     {
         "area": "shape-escape-hatch",
         "matrix_row": "저수준 도형·컨트롤 탈출구",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_shape", "add_control"),
     },
     {
         "area": "curve-objects",
         "matrix_row": "arc·polygon·curve·connectLine",
         "entry_points": (),
+        "authoring_methods": (),
     },
     {
         "area": "picture",
         "matrix_row": "그림 삽입/치환",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_picture", "add_image"),
     },
     {
         "area": "chart",
         "matrix_row": "차트",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_chart",),
     },
     {
         "area": "equation",
         "matrix_row": "수식",
         "entry_points": ("hwpx.equation.authoring:latex_to_eqedit",),
+        "authoring_methods": ("add_equation",),
     },
     {
         "area": "redline",
         "matrix_row": "변경추적(redline)",
         "entry_points": ("hwpx.tools.redline:verify_redline",),
+        "authoring_methods": ("add_track_change", "add_tracked_insert", "add_tracked_delete", "add_tracked_replace"),
     },
     {
         "area": "memo",
         "matrix_row": "메모(코멘트)",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_memo", "add_memo_with_anchor"),
     },
     {
         "area": "footnote-endnote",
         "matrix_row": "각주/미주",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_footnote", "add_endnote"),
     },
     {
         "area": "toc-crossref",
         "matrix_row": "네이티브 목차(TOC)/상호참조",
         "entry_points": ("hwpx.tools.toc_author:add_native_toc",),
+        "authoring_methods": ("add_bookmark", "add_hyperlink"),
     },
     {
         "area": "encrypted-hwpx",
         "matrix_row": "암호화 HWPX",
         "entry_points": (),
+        "authoring_methods": (),
     },
     {
         "area": "hwp5-binary",
         "matrix_row": "HWP 5.x 바이너리",
         "entry_points": (),
+        "authoring_methods": (),
     },
     {
         "area": "form-field-create",
         "matrix_row": "누름틀(form field) 생성",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_form_field",),
+    },
+    {
+        "area": "check-box",
+        "matrix_row": "체크박스 양식개체",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_check_box",),
     },
 )
 
@@ -458,9 +506,110 @@ def contract_json_schema(name: str) -> dict[str, Any]:
     return builder()
 
 
+def verify_self_description() -> list[str]:
+    """설치된 휠에서 자기서술이 실표면과 맞는지 직접 검사한다.
+
+    왜 라이브러리 안에 있나: 5.6.0의 CHANGELOG는 이 부류의 드리프트를 "이제
+    구조적으로 막습니다"라고 **선언**했고, 바로 다음 릴리스에서 같은 드리프트를
+    냈다. 두 번째 선언은 신뢰받을 이유가 없다. 그래서 선언 대신 **누구나 자기
+    설치본에서 돌려 볼 수 있는 검사**를 동봉한다 —
+    ``python -m hwpx.capabilities --verify``.
+
+    저장소의 테스트가 아니라 설치된 패키지에서 도는 것이 요점이다. 사용자가
+    받은 휠이 실제로 무엇을 할 수 있는지 그 휠 자신에게 물어볼 수 있다.
+
+    Returns:
+        위반 목록. 빈 리스트면 자기서술이 실표면과 일치한다.
+    """
+
+    from .document import HwpxDocument
+
+    problems: list[str] = []
+
+    live = {name for name in dir(HwpxDocument) if name.startswith("add_")}
+    registered: dict[str, str] = {}
+    for row in _CAPABILITY_AREAS:
+        for method in row.get("authoring_methods", ()):
+            if method in registered:
+                problems.append(
+                    f"authoring method {method!r} is claimed by both "
+                    f"{registered[method]!r} and {row['area']!r}"
+                )
+            registered[method] = row["area"]
+
+    for method in sorted(live - set(registered)):
+        problems.append(
+            f"HwpxDocument.{method} exists but no capability area claims it; "
+            "the self-description understates what this install can do"
+        )
+    for method in sorted(set(registered) - live):
+        problems.append(
+            f"capability registry claims HwpxDocument.{method}, which this "
+            "install does not have; the self-description overstates it"
+        )
+
+    matrix_rows = {row["matrix_row"] for row in _CAPABILITY_AREAS}
+    try:
+        text = contract_document("support-matrix")
+    except HwpxError as exc:  # pragma: no cover - only when the doc is absent
+        problems.append(f"bundled support matrix is unreadable: {exc}")
+    else:
+        documented = {
+            line.split("|")[1].strip()
+            for line in text.splitlines()
+            if line.startswith("|")
+        }
+        for row in sorted(matrix_rows - documented):
+            problems.append(f"capability area {row!r} has no support-matrix row")
+
+    return problems
+
+
+def _verify_main(argv: list[str] | None = None) -> int:
+    import argparse
+    import json as _json
+    import sys
+
+    parser = argparse.ArgumentParser(
+        prog="python -m hwpx.capabilities",
+        description="Report or verify this install's machine-readable self-description.",
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="check the self-description against the installed surface",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.verify:
+        print(_json.dumps(describe_capabilities(), ensure_ascii=False, indent=2))
+        return 0
+
+    problems = verify_self_description()
+    for problem in problems:
+        print(f"self-description error: {problem}", file=sys.stderr)
+    if problems:
+        print(
+            f"{len(problems)} self-description problem(s) found in "
+            f"python-hwpx {_package_version()}",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"python-hwpx {_package_version()}: self-description matches the "
+        f"installed surface ({len(_CAPABILITY_AREAS)} capability areas)"
+    )
+    return 0
+
+
 __all__ = [
     "CAPABILITIES_SCHEMA",
     "describe_capabilities",
     "contract_document",
     "contract_json_schema",
+    "verify_self_description",
 ]
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(_verify_main())

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/data/contract_docs/support-matrix.md

@@ -23,14 +23,14 @@
 |---|---|---|
 | 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | corpus-metrics「오픈 수용률」476/476, 「저작 품질 게이트」실저작 58/58, 「렌더 검증」416건 |
 | 표 구조 변경(행·열·표 삭제/삽입, 열 오토핏) | Preserve·Edit | `hwpx.table_patch`; corpus-metrics「바이트 보존」497/497(patch 경로) |
-| 표 생성(병합·중첩 포함) | Create·Render-verified | `add_table`·`merge_cells`(피복 셀 제거+cellSpan — 실한컴 병합 의미론과 동형, 3종 병합 렌더 픽셀 확인)·셀 문단 `add_table`(중첩). **알려진 기본값 갭**: 셀 여백 0(한컴 510/141)·기본 폭 고정·중첩 기본 폭이 부모 셀 초과 시 렌더 소실 가능(폭 명시 권장)·선 종류는 raw 전용 — 수리 예정 |
+| 표 생성(병합·중첩 포함) | Create·Render-verified | `add_table`·`merge_cells`(피복 셀 제거+cellSpan — 실한컴 병합 의미론과 동형, 3종 병합 렌더 픽셀 확인)·셀 문단 `add_table`(중첩). 기본값은 5.4.0에서 실한컴에 맞췄다: 셀 안여백 510/510/141/141, 기본 표 폭은 본문 폭, 중첩 표는 부모 셀 사용 폭. **남은 갭**: 선 종류는 raw 전용 |
 | 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch`; corpus-metrics「바이트 보존」497/497. wild 공개 양식의 서식 충실은 2차 실측 후 **산출분 pass 82.1%(23/28)·산출+fail 7.6%(5/66)** — 불가능 타깃은 typed 거부 35건(전수 감별 과잉거부 0). 잔존은 페이지 리플 5건(4건 typed 경고 동반·완전 무음 1건, 「구조결함 2차 실측」절), 표 shape 부류는 측정 인공물로 판명·판정기 교정 |
 | 편집 계획 실행(edit plan) | Preserve·Edit | `hwpx.plan.apply_edit_plan`(experimental, 5.6.0+): 바이트-스플라이스 op 7종을 계획 1파일로 합성 — 정적 선검증→전 체인 인메모리 실행→최종 open-safety 검증→단 1회 원자 쓰기. 중간 실패 시 output·source 바이트 불변(테스트가 바이트 비교로 증명), step별+원본→최종 `hwpx.mutation-report/v1` 실측 사영 |
 | 도형 저작(선·사각형·타원) | Parse·Preserve·Edit·Create·Render-verified | 전용 `add_line`·`add_rectangle`·`add_ellipse`. 5.0.0에서 기하 네임스페이스(`hc:`)·선 bounding box·`resize()`의 기하 반영을 수정한 뒤 실한컴 12.30.0(build 6446)에서 **개봉 7/7**(선 수평·대각·수직, 사각형, 타원, resize 후 혼합, 그림). 렌더로 사각형 144×72pt+`#CCE5FF`, 타원 100×60pt+`#FFD9CC`, 대각선이 요청 박스를 실제 span, `resize(14400,7200)` 후 새 크기·DASH 반영까지 확인 |
 | 저수준 도형·컨트롤 탈출구 | Edit | `add_shape`·`add_control`은 건네받은 요소와 속성만 쓰고 OWPML 필수 하위 요소(`offset`·`orgSz`·`curSz`·`sz`·`pos`·유형별 기하)는 만들지 않는다. 그대로 저장한 문서는 실한컴 12.30.0이 **거부**한다(음성 대조로 확인). 신호는 생성 시점의 `UserWarning` **하나뿐**이다 — 저장을 막지 않고 `validate_package`·`validate_editor_open_safety`도 통과시킨다(실측 `ok=True`). 도형은 위의 전용 헬퍼를 쓸 것(전용 헬퍼는 경고하지 않는다) |
 | arc·polygon·curve·connectLine | Parse·Unsupported-but-preserved | 열거·읽기는 되지만 저작 API 없음. 기존 개체는 patch 저장에서 바이트 동일 왕복 |
 | 그림 삽입/치환 | Edit·Create | `add_picture`·`add_image`·`replace_picture`. 단순 그림 개체 자동 생성은 지원하며 실한컴 개봉을 확인했다(실한컴 코퍼스와 자식 요소 단위 대조). 그룹·효과 등 복잡 개체 생성은 미지원 |
-| 차트 | Unsupported-but-preserved | 차트 생성 API 없음(kordoc 흡수 갭). 기존 차트 part는 patch 저장 시 바이트 보존(497/497) |
+| 차트 | Create(experimental)·Preserve | `add_chart`(5.3.0+): 데이터·계열·축 레이블에서 차트 개체를 생성한다. 기존 차트 part는 patch 저장 시 바이트 보존(497/497). 생성 어휘 밖의 차트 종류·서식은 미지원이며 기존 개체 보존으로만 다룬다 |
 | 수식 | Parse·Create(experimental)·Render-verified | `add_equation`(EqEdit script 삽입, 5.2.0+)과 `hwpx.equation.latex_to_eqedit`(렌더 검증 토큰셋만 변환, 밖은 `UnsupportedLatexError`로 typed 거부). 저작 어휘 전 토큰을 실한컴 렌더 오라클 픽셀 실측(60수식 배터리)으로 확정했고, 기존 수식 개체는 파싱·patch 보존됨(미리보기 MathML 렌더는 뷰어/플러그인 계층) |
 | 변경추적(redline) | Edit·Create | `add_tracked_insert`·`add_tracked_delete`·`add_tracked_replace`; 실 Windows 한컴 COM `IsTrackChange=1`·검토 리본 수락/거부 스파이크. **렌더 주의**: 한컴이 변경추적 문서의 PDF export 자체를 거부 → corpus-metrics「렌더 검증」에서 `render_unavailable`로 정직 집계(결함 아님, 한컴 제약) |
 | 메모(코멘트) | Edit·Create·Render-verified | `add_memo`·`add_memo_with_anchor`; subList 코멘트 텍스트 + `MemoShapeIDRef` 버그 수정을 실 Windows 한컴에서 검증(CHANGELOG) |
@@ -39,6 +39,7 @@
 | 암호화 HWPX | Unsupported-and-rejected | 복호화 API 없음. 암호화된 content part는 파싱 단계에서 예외(`XMLSyntaxError`)로 거부 — 무음으로 잘못된 문서를 만들지 않음(fail-closed) |
 | HWP 5.x 바이너리 | Unsupported-and-rejected | HWP v5는 ZIP이 아니므로 열기 시 `BadZipFile` 예외. OLE2/CFBF 시그니처를 확인하면 예외 메시지가 HWPX 변환을 안내한다(예외 타입은 그대로) |
 | 누름틀(form field) 생성 | Parse·Edit·Create(experimental) | `list_form_fields`·`fill_form_field`로 조회·서식 보존 채움에 더해, `add_form_field`(5.1.0+)가 실한컴 CLICKHERE 계약 그대로 신규 누름틀을 생성한다(표 셀 배치 포함). 만든 필드는 기존 list/fill과 실제 한컴이 특수분기 없이 소비 |
+| 체크박스 양식개체 | Create·Render-verified | `add_check_box`·`list_check_boxes`·`set_check_box`(5.7.0+). 실한컴 실측 계약: `value` CHECKED=☑ / UNCHECKED=□, `<hp:formCharPr>`는 **필수 자식**(없으면 한컴이 문서를 거부하는데 우리 open-safety·ID 무결성은 통과한다 — 실한컴이 유일한 판정자다). 라디오(`hp:radioBtn`)·명령단추(`hp:btn`)는 읽기·보존만 하고 저작 API 없음 |
 
 ## 상태 판정 근거 요약
 

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/layout/report.py

@@ -104,10 +104,19 @@ class LayoutLintReport:
 
         from hwpx.quality.report import LayoutReport
 
+        warnings = [str(f) for f in self.warnings]
+        errors = [str(f) for f in self.errors]
+        if errors:
+            status = "failed"
+        elif warnings:
+            status = "warned"
+        else:
+            status = "passed"
         return LayoutReport(
             ok=self.ok,
-            warnings=[str(f) for f in self.warnings],
-            errors=[str(f) for f in self.errors],
+            warnings=warnings,
+            errors=errors,
+            status=status,
         )
 
     def to_dict(self) -> dict[str, Any]:

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/patch.py

@@ -95,6 +95,21 @@ class BytePreservingPatchResult:
     byte_identical: bool
     zip_method: str
     open_safety: dict[str, Any]
+    #: Edits that matched but were thrown away because another patch skipped.
+    #:
+    #: This family is all-or-nothing: one skip discards the whole set. Those
+    #: edits used to be reported in ``applied``, which said the operation had
+    #: done something it had not. They are reported here instead, so the
+    #: diagnostic value survives without the receipt claiming work.
+    discarded: tuple[PatchApplied, ...] = ()
+    #: True when ``output_path`` received the unmodified source bytes.
+    #:
+    #: The byte-splice family writes ``output_path`` even when everything was
+    #: skipped, so the file exists and opens and is simply not edited. That is
+    #: documented behaviour, kept for consistency across the op family; this
+    #: flag makes it impossible to mistake the written file for an edited one
+    #: without reading prose.
+    output_is_source_copy: bool = False
     # The uniform Phase-B report from the single SavePipeline this byte-path write
     # funnelled through (plan §2 Phase B). Additive and defaulted so existing
     # keyword construction is unaffected.
@@ -116,6 +131,8 @@ class BytePreservingPatchResult:
             "visualComplete": (
                 None if self.visual_complete is None else self.visual_complete.to_dict()
             ),
+            "discarded": [item.to_dict() for item in self.discarded],
+            "outputIsSourceCopy": self.output_is_source_copy,
         }
 
     def as_mutation_report(self, *, source: bytes | str | Path | None = None) -> MutationReport:
@@ -223,16 +240,20 @@ def paragraph_patch(
             changed_parts[section_path] = updated_xml
 
     if skipped:
+        # All-or-nothing: one skip discards the whole set. Report the matched
+        # edits as discarded rather than applied — nothing was applied.
         open_safety, visual_complete = _finalize(source_bytes, output_path, source=source)
         return BytePreservingPatchResult(
             data=source_bytes,
-            applied=tuple(applied),
+            applied=(),
             skipped=tuple(skipped),
             changed_parts=(),
             byte_identical=True,
             zip_method="skipped",
             open_safety=open_safety,
             visual_complete=visual_complete,
+            discarded=tuple(applied),
+            output_is_source_copy=output_path is not None,
         )
 
     if not changed_parts:

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/quality/report.py

@@ -126,17 +126,49 @@ class FormReport:
         return asdict(self)
 
 
+LayoutStatus = Literal["passed", "warned", "failed", "unverified"]
+
+
 @dataclass
 class LayoutReport:
-    """Renderer-less layout lint verdict (LayoutLint lands in Phase D)."""
+    """Renderer-less layout lint verdict (LayoutLint lands in Phase D).
+
+    ``status`` is the explicit tri-state-plus-skip, mirroring
+    ``visual_complete_status`` above. It exists because ``ok`` alone cannot say
+    *why* a report is passing:
+
+    * ``"passed"``     — the lint ran and found nothing.
+    * ``"warned"``     — the lint ran and found non-blocking findings.
+    * ``"failed"``     — the lint ran and found a blocking defect.
+    * ``"unverified"`` — the lint did **not** run (policy disabled it, or it
+      raised). Not a defect, and not evidence of one either.
+
+    Before ``status`` existed, a disabled gate, a gate that raised, and a real
+    pass were all ``LayoutReport.passed()`` and therefore indistinguishable in
+    the receipt. A caller who asked for ``layout_lint="strict"`` could receive a
+    passing receipt because the linter had thrown. That is the same class of
+    error this project names elsewhere as "a score is not a submission": the
+    receipt has to say what actually happened.
+
+    ``ok`` keeps its meaning (does this block the save) so behaviour does not
+    change; ``unverified`` is non-blocking, exactly as an absent render is.
+    """
 
     ok: bool = True
     warnings: list[str] = field(default_factory=list)
     errors: list[str] = field(default_factory=list)
+    status: LayoutStatus = "passed"
+    unverified_reason: str | None = None
 
     @classmethod
     def passed(cls) -> "LayoutReport":
-        return cls(ok=True)
+        return cls(ok=True, status="passed")
+
+    @classmethod
+    def unverified(cls, reason: str) -> "LayoutReport":
+        """The lint did not run. Say so instead of reporting a pass."""
+
+        return cls(ok=True, status="unverified", unverified_reason=reason)
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/quality/save_pipeline.py

@@ -352,7 +352,20 @@ class SavePipeline:
                     )
                 )
         except Exception as exc:  # pragma: no cover - defensive: never crash the gate
-            warnings.append(f"id-integrity check skipped: {type(exc).__name__}: {exc}")
+            # Never crash the gate, but never launder "could not check" into
+            # "checked and fine" either. When the caller explicitly required
+            # reference integrity, an unverified check is not a satisfied one.
+            reason = f"{type(exc).__name__}: {exc}"
+            warnings.append(f"id-integrity check unverified: {reason}")
+            if quality.require_reference_integrity:
+                ok = False
+                errors.append(
+                    QualityError(
+                        REFERENCE_INTEGRITY_FAILED,
+                        "ID/reference integrity was required but could not be "
+                        f"verified: {reason}",
+                    )
+                )
         return ok
 
     def _check_open_safety(
@@ -390,7 +403,7 @@ class SavePipeline:
         """
 
         if quality.layout_lint == "off":
-            return LayoutReport.passed()
+            return LayoutReport.unverified("layout_lint policy is 'off'")
 
         from hwpx.layout.lint import (
             STALE_LINESEG_DETECTED,
@@ -408,8 +421,12 @@ class SavePipeline:
                 required_fields=required_fields,
             )
         except Exception as exc:  # pragma: no cover - defensive: never crash the gate
-            warnings.append(f"layout lint skipped: {type(exc).__name__}: {exc}")
-            return LayoutReport.passed()
+            # Do not crash the gate, but do not report a pass either. A caller
+            # who asked for strict linting and received "passed" because the
+            # linter threw has been told something untrue.
+            reason = f"layout lint raised {type(exc).__name__}: {exc}"
+            warnings.append(f"layout lint unverified: {reason}")
+            return LayoutReport.unverified(reason)
 
         if quality.layout_lint == "warn":
             lint = lint.demote_errors()

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/table_patch.py

@@ -13,7 +13,7 @@ cell addressing on top of the same byte machinery:
 * resolve a logical ``(row, col)`` -- merge aware -- to the covering ``<hp:tc>``,
 * splice **only** that cell's first paragraph text (reusing
   :func:`hwpx.patch._text_edit_for_paragraph`, which handles empty / self-closing
-  ``<hp:run/>`` / ``<hp:t/>`` cells -- the kordoc #4/#30 edge the P0 spike hit),
+  ``<hp:run/>`` / ``<hp:t/>`` cells -- the edge case an early spike hit),
 * strip that paragraph's stale ``<hp:linesegarray>`` so Hancom relayouts,
 * rewrite only the changed section parts through the ZIP partial-patch writer, so
   every untouched byte of the document round-trips identical (Constitution VII).

{python_hwpx-5.7.0 → python_hwpx-5.8.0}/src/hwpx/tools/idempotence.py

@@ -12,11 +12,13 @@ The comparison is at the *part-content* level — the bytes of each ZIP entry
 deliberately ignoring ZIP container metadata (entry mtimes, compression method),
 which are not byte-stable across saves and carry no document meaning.
 
-Following the rhwp roundtrip doctrine: the *first* serializer output may
-legitimately differ from the original input (we strip stale linesegarray,
-normalize, etc.), but once through the serializer the representation must reach
-a fixed point — so we compare round-1 output against round-2 output, not against
-the original source.
+The *first* serializer output may legitimately differ from the original input
+(we strip stale linesegarray, normalize, etc.), but once through the serializer
+the representation must reach a fixed point — so we compare round-1 output
+against round-2 output, not against the original source. Comparing against the
+source instead would fail every legitimate normalization and prove nothing about
+repeat-save stability, which is the property that actually protects a document
+edited many times.
 """
 
 from __future__ import annotations

{python_hwpx-5.7.0 → python_hwpx-5.8.0/src/python_hwpx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.7.0
+Version: 5.8.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -158,10 +158,15 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 실측으로 말합니다
 
-만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
-그대로 공개합니다:
+만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
+스택과 날짜를 병기합니다:
 
-- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
+  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
+  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
+  (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
 - **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
 - 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)