v4.2.0

[4.2.0] - 2026-07-22

Added — 평가계획(교수학습운영·평가계획) 실채움 엔진 확장

• fill_evalplan에 phase="clean"을 추가했습니다 — 기존 "all"(채움) 뒤에 core의
  결정론적 양식 정리(제목·교사·정의적 표 채움, 양식 지시문·외래 샘플 소제목·고아
  헤딩 prune, 빨강 지시 run 제거, 슬롯-파랑→본문 검정 재색, 표 꼬리 캡션 strip)를
  한 경로로 수행해, 별도 정리 스크립트 없이 실제 도교육청 양식을 잔존물 없이
  채웁니다. 기본값 "all"은 기존 동작 그대로입니다(비파괴).
• finalize_evalplan(위 정리 오케스트레이션)과 프리미티브 2종
  (table_patch.strip_trailing_table_captions, guidance_scan.is_form_instruction)을
  추가했습니다. 전부 패턴·구조 기반이며 과목·학년 문자열 하드코딩이 없습니다.

Fixed — 평가계획 표 파싱·채움

• 성취기준별 §4가 성취수준 표(A~E 또는 상/중/하)를 파싱·채우지 못하던 문제를
  고쳤습니다. 콘텐츠의 성취수준 단계 수를 읽어 표 구조에 맞춰 채웁니다.
• 도너 스케줄 표의 병합이 일부 주차 행을 흡수하던 문제를 고쳤습니다(병합 분리).
• §7 수행평가 세부기준 상세 배점 루브릭(평가요소·수행수준·배점, 세부 영역 가/나/다)을
  파싱·채우도록 확장했습니다.

v4.1.1

[4.1.1] - 2026-07-21

Fixed

• 4.1.0 태그의 발행이 공개 위생 게이트(워크스테이션 경로 검사)에 걸려 중단됐습니다
  — 내부 개발용 rhwp 트리아지 스크립트가 공개 레포에 포함돼 있었고, 해당 도구는
  공개 표면이 아니므로 저장소에서 제거했습니다. 라이브러리 코드는 4.1.0과
  동일합니다. (v4.1.0은 보존된 실패 태그이며 PyPI 산출물이 없습니다.)

v4.0.0

[4.0.0] - 2026-07-21

Removed — deprecation window 준수 정리 (major 경계)

• HwpxDocument.save() 제거: v2.6(2026-02-19)부터 5개월간 DeprecationWarning을
  달고 있던 호환 래퍼를 제거했습니다. 목적지별 명시 메서드를 쓰세요 —
  경로 save_to_path(path) · 스트림 save_to_stream(stream) · 바이트 to_bytes().
  이 셋은 안전한 쓰기 계약(mode/fallback 등급 +
  return_report)을 지원하며, 제거된 save()에는 없던 기능입니다.
• hwpx.package 모듈(→hwpx.opc.package)은 경고 이력이 있지만 stable
  HwpxPackage의 역사적 import 경로라 유지합니다(shim, 비용 0). 전체 표·이유는
  4.0.0 마이그레이션.

Added — 구조화 예외 베이스 (오류 계약 통일)

• hwpx.errors.HwpxError(최상위 hwpx.HwpxError로도 import) 도입 — fail-closed 공개
  경로 예외의 베이스. 사람용 str(exc)는 그대로 두고 기계가 읽는 code(kebab
  안정 식별자)·context(실측 값 dict)·suggestion(다음 행동)을 얹으며 to_dict()로
  봉투를 냅니다. 공개 계약 경로부터 이행: PreservationDowngradeError
  (preservation-downgrade), 신규 SaveError(대표 저장 경로의 사전검증·open-safety·
  품질 게이트 실패), TableStructureError(table-structure),
  RenderCheckRequired(render-check-required). 기존 except
  타입(ValueError/RuntimeError/Exception)은 상속으로 그대로 동작합니다.
  전체 표는 stable-api.md 오류 계약.
• HwpxError가 stable 표면에 추가되어 hwpx.__all__은 stable 67개가 됩니다.

Changed — 스키마 동결 + mutation 반환형 통일

• 스키마 동결: hwpx.mutation-report/v1·hwpx.document_plan.v1/v2·
  hwpx.agent-batch/v1·hwpx.mixed-form-plan/v1의 required 필드 집합을 동결하고
  계약 테스트(tests/test_schema_freeze.py)로 고정했습니다. 정책은 additive-only —
  신규 필드는 Optional, 파괴 변경은 새 major + 새 스키마 버전 문자열
  (schema-freeze.md).
• mutation 반환형 통일: 공개 mutation-write 경로가 전부 hwpx.mutation-report/v1로
  사영 가능함을 계약 테스트(tests/test_mutation_contract_unification.py)로 고정
  했습니다(byte-write 결과모델 4종 + 네이티브 save_to_path 영수증). 사영 없는 신규
  byte-write 모델이 추가되면 구조 가드가 실패합니다.
• save_to_path/save_to_stream/to_bytes 이름을 장기 확정으로 명문화(개명 재론
  종결, safe-write-contract.md).

Changed — 최상위 API 표면 3계층화 (major 경계 준비)

• from hwpx import ... 표면을 stable / experimental / deprecated 3계층으로
  분류했습니다. hwpx.__all__에는 stable 67개만 남깁니다(P1의 66 + P2 HwpxError).
  계층·정책 전수 목록은 docs/stable-api.md.
• experimental(12) — ingestion 프레임워크·레이아웃 프리뷰·문서 프리뷰 뷰어.
  from hwpx.experimental import ...로 사용하세요. 최상위 재내보내기는 하위 호환을
  위해 유지하되 접근 시 DeprecationWarning이 나며 다음 major에서 최상위 경로가
  제거될 예정입니다(구현 모듈·hwpx.experimental 경로는 유지).
• deprecated(4) — analyze_template_formfit/apply_template_formfit와
  TEMPLATE_FORMFIT_*_SCHEMA_VERSION 상수 2개. 대체 = 구조적 form-fill 경로
  (hwpx.table_patch.fill_cells 계열 + MCP analyze_form_fill/apply_form_fill/
  verify_form_fill).
• 최상위에서 제거된 이름 0개: 기존 최상위 이름 82개는 전부 계속 import 가능합니다
  (최소 deprecation window 준수 — 경고 없는 즉시 제거 금지). HwpxDocument.save()는
  최상위 표면 이름이 아니라 메서드로, 위 Removed 절에 따라 제거됐습니다.

v3.8.0

[3.8.0] - 2026-07-21

Added — 문서 프리뷰 뷰어

• render_document_viewer: 한컴 없이 문서를 스크롤 통독하는 self-contained
  HTML 뷰어(상단바·현재 페이지 표시·키보드 탐색·외부 리소스 0). 충실도 배지가
  한계를 정직하게 표시합니다(텍스트 근사·페이지네이션은 한컴과 다를 수 있음).
• 수식 실제 렌더: hwpx.equation — <hp:equation>의 EqEdit 스크립트를
  clean-room 토큰맵으로 LaTeX로 변환해 MathML로 렌더합니다(선택 extra
  python-hwpx[preview] = latex2mathml). 실한컴 ground-truth와 시각 대조로
  검증(specs 증거). 변환 불가/라이브러리 부재 시 빈칸 대신 원문·LaTeX
  코드블록으로 정직 표시하고, 그림·도형은 자리표시 마커로 보입니다 — 기존
  프리뷰가 수식을 조용히 빈 문단으로 떨구던 동작은 제거됐습니다.

Internal

• MCP 경계 타이핑 정밀화를 위한 evalplan 경로 Path/str 유니온(순수 어노테이션).
• 복잡도 3물결: 최상위 15개 함수 분해(C901 115→100), characterization 39건 추가.

v3.7.0

[3.7.0] - 2026-07-21

Added — Safe Write Contract

• 일반 저장 경로가 명시적 쓰기 모드를 받습니다:
  save_to_path(path, mode="patch"|"rebuild"|"auto", fallback="error"|"rebuild", return_report=True). 반환 기본값은 기존과 동일(경로)이며 return_report=True
  일 때만 스키마버전드 hwpx.mutation-report/v1 영수증을 반환합니다 —
  요청/실제 모드, 변경 part 목록(+가능한 경우 실제 범위, coordinate space 명시),
  보존 보증 3계층(미수정 part payload / zip local record / whole package),
  수행한 검증의 3값 기록(passed/failed/not_performed).
• 무음 강등 없음: mode="patch"에서 요청 보존 등급을 만족하지 못하면
  출력 파일을 쓰지 않고 typed PreservationDowngradeError를 던집니다.
  fallback="rebuild"로 명시 동의한 경우에만 진행하며 영수증에
  fallbackUsed: true가 남습니다. 보존은 단언이 아니라 open-시점 기준선
  대비 실측입니다(발행 성공 시 기준선 전진).
• 기존 쓰기 결과 4종(BytePreservingPatchResult·CellFillResult·BodyOpsResult·
  AgentBatchResult)에 as_mutation_report() 사영 추가 — byte-splice 계열은
  source=(bytes/str/Path) 제공 시 보존 3계층과 실제 스플라이스 범위를
  실측 보고, 미제공 시 정직 강등. 기존 필드·to_dict 출력은 불변(additive).

Docs

• README 포지셔닝 개정(§안전 자동화 계층+검증된 저작), 지원 매트릭스
  공개(docs/support-matrix.md — Parse/Preserve/Edit/Create/Render-verified/
  Unsupported-but-preserved/Unsupported-and-rejected, 셀별 증거 링크),
  docs/safe-write-contract.md 신설, 헤드라인 지표에 corpus·분모·측정일·
  assurance 병기(오픈 수용률 하한 표기를 rule-of-three 99.37%로 정밀화).

v3.6.0

[3.6.0] - 2026-07-20

Fixed

• 양식 채움 무음 서식파괴의 지배 원인 픽스: fit 슬롯이 셀 안 인라인
  treat-as-char 객체(체크박스·폼컨트롤·그림)의 선언 폭(hp:sz/@width)을
  가용폭에서 차감합니다. 이전에는 이를 비모델링해 "맞음"으로 오판한 채움이
  실한컴에서 줄바꿈·행 성장을 일으켜 다중 페이지 양식 전체를 밀었습니다
  (실측: 3글자 채움이 10페이지 양식을 11페이지로). 이제 그런 채움은 typed
  FIELD_OVERFLOW 거부(컨트롤 동거 경고 포함)가 됩니다. 실한컴 재측정에서
  판정 조합 전체의 무음 서식파괴가 47%→16.7%로 감소했습니다.
• 레이아웃 캐시 무효화를 편집 스코프로 축소: 편집한 문단의 캐시만 제거하고
  저장 시 전량 제거(2개 레이어) 대신 증명 가능한 stale만 걷어냅니다. 채움
  바이트 델타가 −133,651자에서 −170자로 줄어 바이트 보존 계열과 정합합니다.

Added

• SlotMetrics.inline_object_width/inline_object_count — 슬롯 진단 표면.

v3.5.0

[3.5.0] - 2026-07-20

Added

• 양식 채움 fit 판정에 수직(행 높이) 예산을 도입합니다. 이전에는 셀의 가로
  폭만 측정해 세로로 100줄까지 "맞음"으로 판정, 축소도 거부도 발동하지 않고 행이
  조용히 자라 페이지를 밀었습니다. 이제 available_height(셀 높이 − 상하 마진)와
  글꼴별 라인하이트로 세로 예산을 재서, wrap_then_shrink는 값을 예산 안으로
  축소하고, 최소 글꼴에서도 안 들어가는 과대 입력은 overflow="fail"에서 typed
  거부(FIELD_OVERFLOW)로 돌려줍니다. allow_row_expand/expand_row는 명시적
  opt-out입니다. FitPolicy.keep()과 폭-only 경로는 바이트 불변입니다.

Measured (정직 발견)

• wild 공개 양식 전수 재측정(실한컴): 양식 채움 차등이 fit-on 32/63 = 50.8%
  (fit-off 31/63 = 49.2%). 기대-통과 층(short+medium)은 61.4%로 이동 없음 —
  fit은 wild 실패의 지배 레버가 아니며, 지배 원인은 구조적 3부류(채움-겹침·다중
  페이지 경계 밀림·표 구조 민감도)임이 측정됐습니다. 상세는 docs/corpus-metrics.md
  및 leap 데모 demo/S-085-wild-formfill/.

v3.4.1

[3.4.1] - 2026-07-19

Note

• 복구 릴리스. v3.4.0 태그는 prepublish 공개 위생 게이트에서 실패했고
  (테스트 픽스처의 워크스테이션형 경로 문자열 — /home/... 패턴), PyPI
  아티팩트나 GitHub Release는 만들어지지 않았습니다. 실패 태그는 이력으로
  보존하며 3.4.1이 실제 공개 릴리스입니다. 기능 내용은 아래 3.4.0 항목과
  동일합니다.

v3.3.1

[3.3.1] - 2026-07-18

Internal

• 최악 복잡도 검증기 2종을 행동 보존 분해합니다:
  validate_blueprint_manifest(C901 60→1, 헬퍼 14개)와
  validate_package(53→10, 헬퍼 12개). 에러 문자열·검사 순서·manifest 불변성은
  기준선과 verbatim 동일하며 테스트 델타 0으로 실증했습니다.
• 공개 표면·계약 변화는 없습니다. S-083 릴리스 트레인(hwpx-mcp-server 4.3.0 ·
  hwpx-plugin 0.6.0)과 좌표를 맞추는 릴리스입니다.

v3.3.0

[3.3.0] - 2026-07-18

추가

• 선택적 Mac GUI 오라클(MacHancomOracle)에 도달성 프로브를 추가했습니다. 한컴 앱이
  설치돼 있어도 GUI 세션·Automation(TCC) 권한이 없으면 5초 이내에 available() == False로
  정직하게 강등되며(프로세스 수명 캐시), 기존 구조 검증 경로가 그대로 동작합니다.
• 렌더 오라클에 단일 외부 예산 전파를 추가했습니다. budget_seconds(생성자·
  resolve_oracle)가 지정되면 내부의 모든 subprocess 타임아웃이 남은 예산으로
  clamp되고, 예산 소진 시 subprocess를 생성하지 않고 즉시 강등합니다.
• HWPX_ORACLE_STRUCTURAL_ONLY 환경변수를 추가했습니다. 설정 시 resolve_oracle()은
  NullOracle을 반환하고 Mac GUI 백엔드는 어떤 경로로도 GUI 자동화에 진입하지
  않습니다(구조 판정 전용 모드).
• HWPX_ORACLE_BUDGET_SECONDS 환경변수를 추가했습니다. 호스팅 프로세스가 한 번
  선언한 외부 deadline이 resolve_oracle()의 모든 호출 지점(코어 verify·MCP 핸들러)에
  자동 전파됩니다. 명시적 budget_seconds 파라미터가 env보다 우선합니다.

변경

• src/hwpx/visual/oracle.py를 mypy·pyright 점진적 게이트에 편입하고 기존 타입 오류
  2건(textLength 협소화, 검증 항목 변수 재사용)을 수정했습니다.