v0.18.0

Changed (BREAKING)

• cell·stamp·structural 편집기의 입력 decode는 DECODE_FAILED, no-op validate·encode·재decode는 INPUT_NOT_ROUNDTRIP_SAFE, 편집 문서 검증은 VALIDATION_FAILED, 출력 생성은 ENCODE_FAILED, 산출물 검증은 SELF_VERIFY_FAILED로 분류한다. 보호 필드 침범은 PROTECTED_FIELD_RANGE, source-map·provenance 불변식은 INTERNAL_INVARIANT다. CLI·MCP·Python이 같은 코드를 반환한다.
• stamp의 delta 검증 코드는 SELF_VERIFY_FAILED, 같은 셀 중복 지정은 CELL_TARGET_DUPLICATE로 통일한다.
• CLI 종료 상태는 명령과 비공개 typed 코드로 결정하며, 같은 명령·코드의 종료 값은 오류 payload나 발생 경로에 따라 달라지지 않는다. 아래 네 편집기 변경군과 뒤의 I/O 두 변경군, validate 한 변경군(모두 일곱 변경군)을 적용한다.

명령·실패	이전 종료	0.18 종료
delete-para·insert-para: no-op validate·encode·재decode	2	1
stamp: no-op validate·encode·재decode	2	1
set-cell: 입력 decode·원본 패키지 읽기	1	2
delete-para·insert-para: 출력 decode·산출물 읽기·fragment 파싱	2	1

• Draft apply_set_cells 깊이 초과는 CellEditError::NestingTooDeep { section: usize, reason }이며 Display는 nesting depth exceeds the limit: {reason}다. 바이트 입력은 decode 관문에서 먼저 거부한다.

• to_json 은 파서는 통과하지만 Core 중첩 깊이 32단계를 넘는 HWPX 입력에서 GRID_ADDR_PROJECTION_FAILED 대신 읽기 단계의 DECODE_FAILED 를 반환한다.

• stamp-plan 은 이전에 성공하던 같은 깊이 초과 입력을 읽기 단계에서 DECODE_FAILED 로 거부한다.

• fill·stamp·insert-para·delete-para·set-cell·patch 는 같은 깊이 초과 입력에서 이제 decode 단계에서 실패하고, 메시지는 Core error: 를 포함한 깊이 초과 진단으로 바뀐다. 여섯 편집기 모두 아래 단계 분류에 따라 DECODE_FAILED 를 반환한다.

• CLI·MCP는 공통 OpsCode::as_str()를 출력한다. DECODE_ERROR, UNKNOWN_PRESET, INDEX_OUT_OF_RANGE 등의 창구별 별명은 제거한다. 정밀한 기존 도메인 코드와 의미 손실 코드도 그대로 전달한다.

• read의 구역·표·필드 부재는 SECTION_OUT_OF_RANGE, TABLE_NOT_FOUND, FIELD_NOT_FOUND로 통합한다. 관련 read variant 3개와 소비자가 없어진 SectionWorkflowFailed, SetCellFailed, StampFailed, StructuralEditFailed 및 옛 lookup을 삭제한다.

• 입력 부재/기타 읽기/크기 상한/출력 I/O는 FILE_NOT_FOUND/FILE_READ_FAILED/INPUT_TOO_LARGE/FILE_WRITE_FAILED이다. MCP 출력 경로 정책 거부는 INVALID_OUTPUT_PATH이다.

• INVALID_SET·DUPLICATE_SET과 진단용 네 코드, 총 여섯 CLI 전용 코드는 CLI 안에서 유지한다. 입력 부재·읽기 실패는 to-md·convert-hwp5 2, 나머지 1이며 출력 I/O는 구조 편집·convert-hwp5 2, 나머지 1이다. INPUT_TOO_LARGE는 일반 파일 사전 검사·FIFO 모두 1, convert-hwp5의 FILE_WRITE_FAILED는 쓰기·후속 stat 실패 모두 2이다.

• Python 파일 I/O는 HwpForgeError+OSError 계층과 입력 부재 하위 클래스를 사용한다. 광역 catch·OS 필드·copy·pickle을 보존하며 정확한 타입 비교·PermissionError 포착에는 변경이 있다. 부모 디렉터리가 없는 Document.save는 FileNotFoundError 대신 HwpForgeIOError로 포착해야 한다.

• to-pdf·convert-hwp5의 HWP5 디코드 실패는 HWP5_CONVERT_FAILED 대신 HWP5_DECODE_FAILED를 출력한다. convert-hwp5 출력 쓰기 실패는 FILE_WRITE_FAILED, to-md 입력 실패는 FILE_NOT_FOUND·FILE_READ_FAILED·INPUT_TOO_LARGE로 구분한다. 아래 두 I/O 변경군 외의 종료 값은 유지한다.

• MCP 직렬화 실패 SERIALIZE_ERROR·STAMP_MANIFEST_SERIALIZE는 JSON_SERIALIZE_FAILED로 통합한다.

• CLI 구조 편집의 UNCARRIED_ZIP_ENTRIES는 INPUT_ENTRIES_NOT_CARRIED, STRUCTURAL_EDIT_FAILED는 구체 도메인 코드 또는 UPSTREAM_UNMAPPED로 전달한다.

• set-cell·stamp의 의미 손실은 SET_CELL_CODEC_FAILED·STAMP_CODEC_FAILED 대신 ENCODE_SEMANTIC_LOSS이다.

• patch·fill 의 오류를 실패 단계와 원인으로 나눈다. 입구 검사를 통과한 뒤 원본을 읽거나 decode 하지 못하면 PATCH_FAILED·FILL_FAILED 대신 DECODE_FAILED 다. 편집한 문서의 검증 실패는 VALIDATION_FAILED, 출력 작성 실패는 ENCODE_FAILED, 보호 필드의 값·범위 변경은 PROTECTED_FIELD_RANGE, 내부 source map·위치 불변식 파손은 INTERNAL_INVARIANT 다. PATCH_FAILED 는 보존 patch 가 받지 않는 변경과 metadata 부재·불일치에만, FILL_FAILED 는 필드 목록 진단에만 남는다.

• fill 은 내부 patch 의 원인을 그대로 전달하므로 PATCH_FAILED 도 낼 수 있다(예: 다시 만들 수 없는 인라인 표지가 든 칸). 검사 순서는 그대로라 metadata 가 없고 XML 도 손상된 patch 는 계속 PATCH_FAILED 다. CLI 종료 값은 두 명령 모두 바뀐 코드에서도 이전 PATCH_FAILED·FILL_FAILED 와 같은 2 다(patch 의 구역 범위 거부 SECTION_OUT_OF_RANGE 1 은 그대로).

• convert-hwp5·to-pdf(CLI)와 Python convert_hwp5·to_pdf 의 HWP5 변환 실패도 단계별 코드를 낸다. 읽은 문서의 Core 검증 실패는 VALIDATION_FAILED, HWPX 출력 생성 실패는 ENCODE_FAILED 이고, 디코더가 스스로 거부한 스타일·테두리 참조(예: 정의가 없는 표 테두리 번호)는 HWP5_CONVERT_FAILED 대신 HWP5_DECODE_FAILED 다. HWP5_CONVERT_FAILED 는 생성한 패키지에 줄 배치 정보를 다시 입히는 단계에만 남는다. 두 CLI 명령의 종료 값은 바뀐 코드에서도 이전과 같은 2 이고, 힌트도 그대로다. Python convert_hwp5·Document.to_pdf 에서는 디코더가 거부한 참조의 힌트가 코드를 따라 Check that the source is a supported HWP5 document 에서 Check that the file is a valid HWP5 document 로 바뀐다(검증·출력 생성 실패의 힌트는 그대로).

I/O와 validate의 종료 값 변경은 다음과 같다. 편집기의 네 변경군은 위 표에 적었다.

명령·실패	이전 코드·종료	0.18 코드·종료
to-md·convert-hwp5의 크기 한도를 넘는 FIFO 입력	DECODE_FAILED·HWP5_DECODE_FAILED / 2	INPUT_TOO_LARGE / 1
convert-hwp5의 쓰기 성공 직후 stat 실패	FILE_WRITE_FAILED / 1	FILE_WRITE_FAILED / 2
validate: 파서는 통과하고 Core 중첩 깊이가 32 를 넘는 HWPX	판정(valid:false) / 3	DECODE_FAILED / 2

• validate 는 파서는 통과하지만 Core 중첩 깊이가 32 를 넘는 HWPX 에서 판정(valid:false) 대신 DECODE_FAILED 로 실패한다. HWPX decode 진입점이 이 깊이를 거부하기 때문이며(오류 E4008), 파서 한도(표 중첩·XML 예산)에 걸린 문서는 0.17.1 에서도 DECODE_FAILED 였으므로 그대로다. 이행: Rust ops 의 validate 는 Ok(ValidateOutput { ok: false, .. }) 대신 Err 를 반환하고, MCP hwpforge_validate 는 valid:false 데이터 대신 도구 오류를 반환하며, Python Document.validate() 는 ok: False 를 돌려주지 않고 코드 DECODE_FAILED 의 HwpForgeError 를 일으킨다. CLI 는 stdout 판정과 종료 3 대신 stderr 의 DECODE_FAILED 와 종료 2 를 낸다. 깊이 초과를 판정으로 받던 호출부는 오류 경로에서 처리한다.
• HWPX에서 읽은 본문의 CR이 \r 대신 \n으로 나온다(to-json, Python, MCP, 무손실 Markdown). 이행: \r에 기대던 코드를 고치고, 0.17에서 내보낸 보존 metadata 중 CR이 든 칸이 있으면 다시 내보낸 뒤 patch한다. 자세한 것은 hwpforge-smithy-hwpx 항목을 본다.

Changed

• hwpforge-* 크레이트끼리의 의존 요구가 "0"(0.x 아무 버전) 대신 릴리스 버전(예: "0.18.0")을 최소 버전으로 요구한다. 그래서 cargo 가 이 의존에 다른 hwpforge-* 크레이트의 이전 minor 를 고르지 않는다. hwpforge-* 를 직접 여러 개 의존한다면 함께 올린다.
• INPUT_NOT_ROUNDTRIP_SAFE 힌트는 코덱 갭 수정 대기 안내 대신 원본을 보존하는 텍스트 to-json(section) → patch·누름틀 fill 경로를 안내한다. MCP stamp도 해당 도구 이름으로 같은 안내를 제공한다.

Fixed

• convert(CLI·MCP·Python convert_md)가 Markdown 의 대상이 빈 이미지(![x]())를 0.17.0 처럼 IMAGE_EMBED_SKIPPED 경고와 함께 뺀다. 0.17.1 에서는 경고 없이 50×30mm 빈 그림 틀로 남았다. 한컴이 자산을 잃은 채 저장한 그림 틀(#266)은 그대로 남는다.
• HWPX 구역(<hs:sec>) 바로 아래에 놓여 읽지 못하는 글·요소·<hp:t> 를 CONTENT_LOST (section_content) 경고로 알리고, restyle·set-cell·stamp 는 그런 문서를 거부한다. 전에는 경고 없이 그 글을 뺐다. 자세한 것은 hwpforge-smithy-hwpx 항목을 본다.
• HWP 묶음 안 그림의 테두리 손실 경고가 손실을 판정한 선 종류를 함께 적는다(border: line type 2, thickness 0). 전에는 두께만 적어, 두께 0 인 테두리가 왜 손실인지 보이지 않았다(#256 후속).

업그레이드 주의

• HWP 변환의 깊이 초과: HWP5 디코더는 컨테이너마다 깊이를 1씩 세어 32에서 멈추지만 Core 는 캡션·묶음 안 도형을 한 겹에 2 이상으로 센다. 그래서 디코더 상한 안의 HWP 문서도 Core 깊이 32단계를 넘으면 convert-hwp5·to-pdf 와 Python convert_hwp5 가 VALIDATION_FAILED 로 실패할 수 있다. 0.17.1 의 깊이 한도(#267)가 HWP 변환에도 걸린다는 뜻이다. 실제 HWP 문서에서 이렇게 실패하는 경우는 측정하지 않았다.
• 스킬 위치 (#270, 0.17.1): 저장소의 에이전트 스킬이 .claude/skills/ 에서 skills/ 로 옮겨졌다. 0.17.1 CHANGELOG 에 빠졌던 항목이다.