python-hwpx 3.5.0__tar.gz → 3.7.0__tar.gz

{python_hwpx-3.5.0/src/python_hwpx.egg-info → python_hwpx-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.5.0
+Version: 3.7.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -46,7 +46,7 @@ Dynamic: license-file
 <p align="center">
   <h1 align="center">python-hwpx</h1>
   <p align="center">
-    <strong>한글 없이 HWPX 문서를 Python으로 읽고, 편집하고, 생성하고, 구조를 검증합니다.</strong>
+    <strong>한컴 없이 HWPX를 안전하게 자동화하는 Python 계층 — 최소 범위 편집, 검증된 저작, 모든 쓰기에 영수증.</strong>
   </p>
   <p align="center">
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
@@ -56,6 +56,23 @@ Dynamic: license-file
   </p>
 </p>
 
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+---
+
+> **python-hwpx는 한컴 없이 HWPX를 안전하게 자동화하는 Python 계층입니다.** 기존
+> 문서는 최소 범위만 수정하고, 새 문서는 실제 한컴 수용이 검증된 형태로 생성하며,
+> 모든 쓰기에 변경·보존·검증 영수증을 남기고, 완전한 해석과 렌더링은 전문 백엔드에
+> 위임할 수 있습니다.
+
+- **최소 범위 편집** — 미수정 part는 저장 시 바이트 그대로 유지됩니다(patch 경로
+  바이트 보존 497/497, 동결 코퍼스 v2 · 2026-07-19).
+- **검증된 저작** — 밑바닥 생성도 실제 한컴이 받아들이는 형태로 냅니다(산출물 한컴
+  오픈 476/476 all-pass, 실저작 품질 게이트 58/58).
+- **모든 쓰기에 영수증** — 대표 저장 경로는 [Safe Write Contract](docs/safe-write-contract.md)의
+  `MutationReport`(`hwpx.mutation-report/v1`)로 실제 쓰기 모드·보존 등급·검증 결과를
+  **측정해** 반환합니다.
+
 ---
 
 ## 🧩 HWPX Stack (3종)
@@ -70,7 +87,7 @@ Dynamic: license-file
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.5.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.7.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
@@ -80,13 +97,17 @@ Dynamic: license-file
 ## 실측으로 말합니다 — Published Corpus
 
 이 스택의 산출물은 주장 대신 **실제 한컴오피스 전수 측정**으로 검증됩니다
-(동결 코퍼스 N=497, 2026-07-19, 상세·주의사항은
+(동결 코퍼스 v2, N=497 산출물, 2026-07-19, 실한컴 12.0.0.3288 COM/GUI 오라클;
+상세·주의사항은
 [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)):
 
-- **한컴 오픈 수용률 100%** (476/476 all-pass, 하한 ≥99.4%) · 파싱 96.2%
-- **미수정 영역 바이트 보존 100%** (497/497, patch 경로) · **개인정보 0-leak**
-- 렌더 검증 416건 + 정직 버킷(변경추적 문서의 PDF export는 한컴 자체가 거부 — 실측 한계로 발행)
-- 양식 채움 차등은 wild 공개 양식에서 49.2% — **낮은 숫자도 그대로 발행**하고 잔여 과제로 명기합니다
+- **한컴 오픈 수용률 476/476 all-pass** (동결 코퍼스 v2 · 2026-07-19 · 실한컴 COM
+  `Open()` 판정 · rule-of-three 하한 99.37%) · 파싱 96.2%(458/476)
+- **미수정 영역 바이트 보존 497/497** (patch 경로 한정, zip-part diff · 오라클 불요)
+  · **개인정보 0-leak** (35문서/합성 140값)
+- 렌더 검증 416/476 (실한컴 `SaveAs("PDF")`) + 정직 버킷 43건(변경추적 문서의 PDF
+  export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
+- wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
 
 > 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
 > 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
@@ -195,6 +216,59 @@ hwpx-analyze-template 보고서.hwpx
 
 > 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
 
+## 안전한 쓰기 계약 (Safe Write Contract)
+
+대표 저장 경로(`save_to_path` · `save_to_stream` · `to_bytes`)는 **요청한 보존 등급을
+쓰기 전에 판정하고, 실제로 무엇을 바꿨는지 측정한 영수증**을 돌려줍니다.
+
+```python
+from hwpx.mutation_report import PreservationDowngradeError
+
+# 영수증과 함께 저장 — 달성 가능한 가장 강한 보존 등급 자동 선택(mode="auto" 기본)
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)                                   # "patch" | "rebuild"
+print(report.preservation.untouched_part_payloads.to_dict())  # {"verified": 17, "changed": 0}
+
+# patch 등급 강제 — 미달이면 아무것도 쓰지 않고 예외(fail-closed)
+try:
+    doc.save_to_path("결과.hwpx", mode="patch", fallback="error")
+except PreservationDowngradeError as exc:
+    print(exc.offending_parts, exc.suggestion)
+```
+
+- `mode="patch" | "rebuild" | "auto"`(기본 `auto`) · `fallback="error" | "rebuild"`(기본 `error`)
+- `mode="patch"` + `fallback="error"`에서 미수정 part의 바이트 동일성을 지킬 수 없으면
+  **아무것도 쓰지 않고** `PreservationDowngradeError`를 던집니다(무음 rebuild 없음).
+- `MutationReport`는 `requestedMode`/`actualMode`/`fallbackUsed`, 변경 part와 좌표 명시
+  범위, 보존 3층(part 페이로드·ZIP 레코드·전체 패키지), 검증 3항목(`passed`/`failed`/`not_performed`)을
+  **측정해** 반환합니다.
+
+> 파라미터 전체와 `MutationReport` 스키마는 [안전한 쓰기 계약 문서](docs/safe-write-contract.md)를 참고하세요.
+
+## 지원 매트릭스
+
+능력 영역별 실제 등급입니다(동결 코퍼스 v2 · 2026-07-19 · 실한컴 12.0.0.3288 오라클).
+등급 어휘: **Parse / Preserve / Edit / Create / Render-verified /
+Unsupported-but-preserved / Unsupported-and-rejected**.
+
+| 능력 영역 | 상태 | 증거 |
+|---|---|---|
+| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | 오픈 476/476 · 실저작 게이트 58/58 · 렌더 416 |
+| 표 구조 변경(행·열·표, 오토핏) | Preserve·Edit | `hwpx.table_patch` · 바이트 보존 497/497 |
+| 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch` · 보존 497/497 (wild 무음 서식파괴 16.7%·typed 거부 35/66, 잔여 명명) |
+| 그림 삽입/치환 | Edit·Create | `add_picture`·`replace_picture` (복잡 개체는 한컴 확인 권장) |
+| 차트 | Unsupported-but-preserved | 생성 API 없음 · 기존 차트 part는 patch 보존 |
+| 수식 | Parse·Unsupported-but-preserved | 저작 API 없음 · 기존 수식 파싱·patch 보존 |
+| 변경추적(redline) | Edit·Create | `add_tracked_*` · 실한컴 `IsTrackChange=1` (한컴이 PDF export 거부 → `render_unavailable` 정직 집계) |
+| 메모(코멘트) | Edit·Create·Render-verified | `add_memo*` · 실 Windows 한컴 검증 |
+| 각주/미주 | Edit·Create | `add_footnote`·`add_endnote` (렌더 독립 게이트 미측정) |
+| 네이티브 목차/상호참조 | Create·Render-verified | `add_native_toc`·`toc_verify` · 구조 15/15 · 페이지 정합 5/5 |
+| 암호화 HWPX | Unsupported-and-rejected | 복호화 없음 · 암호화 part는 파싱 단계 예외로 거부 |
+| HWP 5.x 바이너리 | Unsupported-and-rejected | ZIP 아님 → 열기 시 `BadZipFile` (HWPX로 변환 후 사용) |
+| 누름틀(form field) 생성 | Parse·Edit | 기존 필드 조회·서식보존 채움 · **신규 누름틀 생성 도구는 미제공** |
+
+> 각 등급의 판정 근거와 상세 증거 포인터는 [지원 매트릭스 문서](docs/support-matrix.md)를 참고하세요.
+
 ## 대항 라이브러리 비교
 
 | | python-hwpx | pyhwpx | pyhwp |
@@ -219,6 +293,7 @@ hwpx-analyze-template 보고서.hwpx
 - **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
 - **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
 - **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
+- **[🔬 HWPX 내부 실전 가이드](docs/internals/)** — 실제 한/글 동작에서 확인된 HWPUNIT·조판 캐시·목차 필드·OPC 재패킹·메모·오라클 한계
 - **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
 - **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
 

{python_hwpx-3.5.0 → python_hwpx-3.7.0}/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <h1 align="center">python-hwpx</h1>
   <p align="center">
-    <strong>한글 없이 HWPX 문서를 Python으로 읽고, 편집하고, 생성하고, 구조를 검증합니다.</strong>
+    <strong>한컴 없이 HWPX를 안전하게 자동화하는 Python 계층 — 최소 범위 편집, 검증된 저작, 모든 쓰기에 영수증.</strong>
   </p>
   <p align="center">
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
@@ -11,6 +11,23 @@
   </p>
 </p>
 
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+---
+
+> **python-hwpx는 한컴 없이 HWPX를 안전하게 자동화하는 Python 계층입니다.** 기존
+> 문서는 최소 범위만 수정하고, 새 문서는 실제 한컴 수용이 검증된 형태로 생성하며,
+> 모든 쓰기에 변경·보존·검증 영수증을 남기고, 완전한 해석과 렌더링은 전문 백엔드에
+> 위임할 수 있습니다.
+
+- **최소 범위 편집** — 미수정 part는 저장 시 바이트 그대로 유지됩니다(patch 경로
+  바이트 보존 497/497, 동결 코퍼스 v2 · 2026-07-19).
+- **검증된 저작** — 밑바닥 생성도 실제 한컴이 받아들이는 형태로 냅니다(산출물 한컴
+  오픈 476/476 all-pass, 실저작 품질 게이트 58/58).
+- **모든 쓰기에 영수증** — 대표 저장 경로는 [Safe Write Contract](docs/safe-write-contract.md)의
+  `MutationReport`(`hwpx.mutation-report/v1`)로 실제 쓰기 모드·보존 등급·검증 결과를
+  **측정해** 반환합니다.
+
 ---
 
 ## 🧩 HWPX Stack (3종)
@@ -25,7 +42,7 @@
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.5.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.7.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
@@ -35,13 +52,17 @@
 ## 실측으로 말합니다 — Published Corpus
 
 이 스택의 산출물은 주장 대신 **실제 한컴오피스 전수 측정**으로 검증됩니다
-(동결 코퍼스 N=497, 2026-07-19, 상세·주의사항은
+(동결 코퍼스 v2, N=497 산출물, 2026-07-19, 실한컴 12.0.0.3288 COM/GUI 오라클;
+상세·주의사항은
 [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)):
 
-- **한컴 오픈 수용률 100%** (476/476 all-pass, 하한 ≥99.4%) · 파싱 96.2%
-- **미수정 영역 바이트 보존 100%** (497/497, patch 경로) · **개인정보 0-leak**
-- 렌더 검증 416건 + 정직 버킷(변경추적 문서의 PDF export는 한컴 자체가 거부 — 실측 한계로 발행)
-- 양식 채움 차등은 wild 공개 양식에서 49.2% — **낮은 숫자도 그대로 발행**하고 잔여 과제로 명기합니다
+- **한컴 오픈 수용률 476/476 all-pass** (동결 코퍼스 v2 · 2026-07-19 · 실한컴 COM
+  `Open()` 판정 · rule-of-three 하한 99.37%) · 파싱 96.2%(458/476)
+- **미수정 영역 바이트 보존 497/497** (patch 경로 한정, zip-part diff · 오라클 불요)
+  · **개인정보 0-leak** (35문서/합성 140값)
+- 렌더 검증 416/476 (실한컴 `SaveAs("PDF")`) + 정직 버킷 43건(변경추적 문서의 PDF
+  export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
+- wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
 
 > 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
 > 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
@@ -150,6 +171,59 @@ hwpx-analyze-template 보고서.hwpx
 
 > 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
 
+## 안전한 쓰기 계약 (Safe Write Contract)
+
+대표 저장 경로(`save_to_path` · `save_to_stream` · `to_bytes`)는 **요청한 보존 등급을
+쓰기 전에 판정하고, 실제로 무엇을 바꿨는지 측정한 영수증**을 돌려줍니다.
+
+```python
+from hwpx.mutation_report import PreservationDowngradeError
+
+# 영수증과 함께 저장 — 달성 가능한 가장 강한 보존 등급 자동 선택(mode="auto" 기본)
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)                                   # "patch" | "rebuild"
+print(report.preservation.untouched_part_payloads.to_dict())  # {"verified": 17, "changed": 0}
+
+# patch 등급 강제 — 미달이면 아무것도 쓰지 않고 예외(fail-closed)
+try:
+    doc.save_to_path("결과.hwpx", mode="patch", fallback="error")
+except PreservationDowngradeError as exc:
+    print(exc.offending_parts, exc.suggestion)
+```
+
+- `mode="patch" | "rebuild" | "auto"`(기본 `auto`) · `fallback="error" | "rebuild"`(기본 `error`)
+- `mode="patch"` + `fallback="error"`에서 미수정 part의 바이트 동일성을 지킬 수 없으면
+  **아무것도 쓰지 않고** `PreservationDowngradeError`를 던집니다(무음 rebuild 없음).
+- `MutationReport`는 `requestedMode`/`actualMode`/`fallbackUsed`, 변경 part와 좌표 명시
+  범위, 보존 3층(part 페이로드·ZIP 레코드·전체 패키지), 검증 3항목(`passed`/`failed`/`not_performed`)을
+  **측정해** 반환합니다.
+
+> 파라미터 전체와 `MutationReport` 스키마는 [안전한 쓰기 계약 문서](docs/safe-write-contract.md)를 참고하세요.
+
+## 지원 매트릭스
+
+능력 영역별 실제 등급입니다(동결 코퍼스 v2 · 2026-07-19 · 실한컴 12.0.0.3288 오라클).
+등급 어휘: **Parse / Preserve / Edit / Create / Render-verified /
+Unsupported-but-preserved / Unsupported-and-rejected**.
+
+| 능력 영역 | 상태 | 증거 |
+|---|---|---|
+| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | 오픈 476/476 · 실저작 게이트 58/58 · 렌더 416 |
+| 표 구조 변경(행·열·표, 오토핏) | Preserve·Edit | `hwpx.table_patch` · 바이트 보존 497/497 |
+| 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch` · 보존 497/497 (wild 무음 서식파괴 16.7%·typed 거부 35/66, 잔여 명명) |
+| 그림 삽입/치환 | Edit·Create | `add_picture`·`replace_picture` (복잡 개체는 한컴 확인 권장) |
+| 차트 | Unsupported-but-preserved | 생성 API 없음 · 기존 차트 part는 patch 보존 |
+| 수식 | Parse·Unsupported-but-preserved | 저작 API 없음 · 기존 수식 파싱·patch 보존 |
+| 변경추적(redline) | Edit·Create | `add_tracked_*` · 실한컴 `IsTrackChange=1` (한컴이 PDF export 거부 → `render_unavailable` 정직 집계) |
+| 메모(코멘트) | Edit·Create·Render-verified | `add_memo*` · 실 Windows 한컴 검증 |
+| 각주/미주 | Edit·Create | `add_footnote`·`add_endnote` (렌더 독립 게이트 미측정) |
+| 네이티브 목차/상호참조 | Create·Render-verified | `add_native_toc`·`toc_verify` · 구조 15/15 · 페이지 정합 5/5 |
+| 암호화 HWPX | Unsupported-and-rejected | 복호화 없음 · 암호화 part는 파싱 단계 예외로 거부 |
+| HWP 5.x 바이너리 | Unsupported-and-rejected | ZIP 아님 → 열기 시 `BadZipFile` (HWPX로 변환 후 사용) |
+| 누름틀(form field) 생성 | Parse·Edit | 기존 필드 조회·서식보존 채움 · **신규 누름틀 생성 도구는 미제공** |
+
+> 각 등급의 판정 근거와 상세 증거 포인터는 [지원 매트릭스 문서](docs/support-matrix.md)를 참고하세요.
+
 ## 대항 라이브러리 비교
 
 | | python-hwpx | pyhwpx | pyhwp |
@@ -174,6 +248,7 @@ hwpx-analyze-template 보고서.hwpx
 - **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
 - **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
 - **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
+- **[🔬 HWPX 내부 실전 가이드](docs/internals/)** — 실제 한/글 동작에서 확인된 HWPUNIT·조판 캐시·목차 필드·OPC 재패킹·메모·오라클 한계
 - **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
 - **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
 

{python_hwpx-3.5.0 → python_hwpx-3.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.5.0"
+version = "3.7.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -109,6 +109,7 @@ python_version = "3.10"
 follow_imports = "skip"
 files = [
     "src/hwpx/document.py",
+    "src/hwpx/mutation_report.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -156,6 +157,7 @@ ignore_missing_imports = true
 # both central facades and every extracted/touched runtime owner to the gate.
 include = [
     "src/hwpx/document.py",
+    "src/hwpx/mutation_report.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",

{python_hwpx-3.5.0 → python_hwpx-3.7.0}/src/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",

{python_hwpx-3.5.0 → python_hwpx-3.7.0}/src/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(

{python_hwpx-3.5.0 → python_hwpx-3.7.0}/src/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(