4.x 호환 표면 관찰 정책

python-hwpx 4.x의 기존 import, CLI, 스키마/리포트 버전, 워크플로 래퍼는 계속 동작한다. 런타임의 정본이 MCP 서버로 이동했더라도 4.x에서 공개 호환 표면을 제거하지 않는다.

이 문서는 2026-07-24에 시작한 공개 관찰의 기준이다. 관찰은 2026-10-31(Asia/Seoul)까지, 최소 90일 동안 진행한다. 의견과 실제 사용 사례는 호환 표면 관찰 이슈에 남길 수 있다.

현재 결정

• 관찰 시작 시점의 제거 권고는 0건이다.

• 아래 8개 family, 3개 CLI를 모두 extend한다.

• deprecated 표시는 새 코드가 canonical 경로를 선택하도록 돕는 안내이며, 이 관찰 자체가 제거 승인은 아니다.

• 4.x에서는 보안 또는 정확성 수정만 양쪽 런타임에 parity test와 영수증을 동반해 mirror한다. 신규 application workflow는 MCP 정본에 둔다.

• 어떤 제거도 관찰 종료 뒤 별도로 승인된 core major에서만 검토한다.

extend는 “계속 사용을 권장한다”는 뜻이 아니라 “호환을 유지하며 실제 사용을 더 관찰한다”는 뜻이다. 새 코드는 아래 canonical 경로를 우선한다.

전체 family 판정

qualified import 수는 공개 모듈별 재내보내기까지 센 호환 projection 수다. 중복 없는 기능 수나 사용량으로 해석하면 안 된다.

4.x 호환 family	qualified import	새 코드의 canonical 경로	판정
agent runtime	219	MCP agent-document/mixed-form 도구; 재사용 가능한 OXML·mutation은 core	extend
authoring runtime	79	MCP authoring/generation/layout/style 도구; 재사용 가능한 object model은 core	extend
compliance/quality/utilities	20	MCP official-document, PII, page-quality, table-utility 도구	extend
form-fill runtime	103	analyze_form_fill → apply_form_fill → verify_form_fill	extend
eval-plan runtime	14	MCP apply_evalplan_fill(phase="clean") + J1~J6 skill workflow	extend
exam runtime	20	MCP compose_exam + exam skill workflow	extend
visual application runtime	30	MCP rendering/oracle/worker/page-QA runtime	extend
document-operations wrappers	3	MCP comparison, PII-aware mail merge, canonical-render redline verification	extend

core에 남는 재사용 가능한 구조·알고리즘 계약은 계속 core API다. MCP가 정본인 것은 workspace policy, orchestration, client ToolSpec, 렌더 worker 같은 application runtime이다.

CLI와 스키마/리포트

다음 console entry point도 4.x에서 유지한다.

명령	entry point	새 자동화의 우선 경로	판정
hwpx	hwpx.agent.cli:main	MCP agent-document 도구	extend
hwpx-analyze-template	hwpx.tools.template_analyzer:main	MCP authoring/template 분석 도구	extend
hwpx-page-guard	hwpx.tools.page_guard:main	MCP page-quality 도구	extend

공개 스키마와 리포트 버전 문자열도 4.x에서 유지한다. 관찰 기준에는 모듈별 재내보내기를 포함한 46개 projection이 있으며, 기존 버전의 required 필드를 바꾸지 않는다. additive 확장은 Optional 필드로만 하고, 파괴 변경은 새 스키마 버전과 별도 major 승인이 필요하다.

알려진 독립 사용

공개 코드 검색에서 core를 MCP 없이 직접 쓰는 사용을 확인했다. 예를 들어 hwpx.builder로 Markdown을 HWPX로 만드는 경로, hwpx.tools.template_analyzer 직접 호출, official lint, template/mail-merge, 두 CLI를 번들에서 호출하는 사용이 있다. 따라서 “검색 결과가 적다” 또는 “MCP에 정본이 있다”만으로 zero-use를 주장하지 않는다.

이행과 rollback

기존 import나 CLI는 즉시 바꿀 필요가 없다. 신규 코드는 위 표의 canonical 경로를 쓰고, 기존 경로는 한 번에 한 family씩 이행한다.

1. 현재 입력과 결과 리포트를 fixture로 고정한다.

2. canonical MCP 경로를 side-by-side로 실행해 의미 결과와 오류 계약을 비교한다.

3. parity와 설치 환경 검증이 통과한 뒤 호출자를 전환한다.

4. 문제가 있으면 호출자를 4.x 호환 경로로 되돌린다. 패키지나 스키마를 downgrade할 필요는 없다.

호환 경로의 보안·정확성 결함은 관찰 이슈에 재현 입력, 사용한 import/CLI, 기대 결과를 함께 남긴다. 관찰 기간에도 해당 수정은 허용하지만, 기능 확장은 canonical MCP owner에 먼저 구현한다.

관찰 종료 뒤

2026-10-31이 지나도 자동으로 제거되지 않는다. 종료 census는 family·qualified import·CLI·스키마/리포트·워크플로별로 keep/remove/extend 근거를 다시 만들고, 사용자 피드백과 clean-install parity/rollback 증거를 포함해야 한다. 실제 제거는 그 자료를 검토해 별도로 승인한 다음 core major에서만 가능하다.