Known-leak migration contract
The layer leak guard (see product-boundary.md) lists
genre and policy logic that still lives in core as known-leak. This document
is the contract for moving it to python-hwpx-automation: for each group, who
owns it afterwards, what core keeps, what callers use instead, and how the core
names are retired. known-leak-migration.json
holds the same decisions in machine-readable form, and
tests/test_known_leak_migration_contract.py keeps it in step with
tests/data/layer_leak_allowlist.json.
Two of the four groups have moved: official-reference-policy and
report-heading-guess went with the whole conversion and guessing move to
python-hwpx-automation (7.0: the reference consistency lint and the Markdown
exporter left core together, so their names were removed without the warning
step; see migration-7.0.md). For the two
groups left, the owner chose how the core names are retired (option A under
Compatibility below): they keep working through 6.x, warn in the next major
and go in the major after it. Releases are named only relative to each other in
the JSON contract; nothing there promises a version number or a date.
The placement test is the one in product-boundary.md: generic HWPX capability stays in core; a deterministic workflow or policy built from core primitives goes to automation. Core never imports automation, so every move below hands core a neutral primitive and puts the policy on the automation side, where it is passed in or applied before calling core.
The additive neutral core seams that stay are implemented in this source tree:
hwpx.tools.doc_diff.paragraph_texts and
hwpx.table_patch.strip_trailing_table_text(predicate=...) (the rich exporter’s
heading_detector callback moved with the exporter). Existing core names and
defaults of the two remaining groups continue without new warnings; their two
compatibility leak entries remain. See
neutral primitives.
The moved groups
official-reference-policy — moved
inspect_reference_consistency, REFERENCE_CONSISTENCY_REPORT_VERSION and the
attachment/table/figure numbering rules left tools/doc_diff.py for
hwpx_automation.office.compliance (same reference-consistency-v1 report).
Core keeps diff_paragraphs, doc_diff and paragraph_texts. The old names
raise an ImportError that names the new place.
report-heading-guess — moved
ARABIC_HEAD, ROMAN_HEAD and _detect_heading left with the whole rich
Markdown exporter (tools/markdown_export.py) for hwpx_automation.markdown;
document ingest went to hwpx_automation.ingest. Core no longer exports
Markdown, so no heading is guessed in core.
The two remaining groups
The two allowlist names left (one known-leak entry, one undetected) fall
into two groups. _OUTLINE_STYLE_NAME (Hancom’s built-in outline style names)
is format-vocabulary and stays.
document-plan-input — automation plan interpretation
Core name:
tools/doc_diff.py_paragraphs_from_document_planand the{"sections": ...}branch of the source dispatch it serves.Canonical owner:
hwpx_automation.office.document_ops.Core keeps: documents, paths, text, paragraph sequences and
{"paragraphs"}/{"text"}mappings as diff and check input.Replacement: an automation function that turns a document plan (
sections/blocks/children, heading and paragraph text, table rows) into the paragraph sequence core takes; automation’s comparison and reference-check entry points call it first.Core surface affected: an input shape of two stable functions — behaviour rather than a name.
evalplan-caption-cleanup — evaluation-plan caption cleanup
Core name:
table_patch.pystrip_trailing_table_captions(its(N) wordpattern has no Hangul, so it is listed as undetected).Canonical owner:
hwpx_automation.office.evalplan.Core keeps: a byte-preserving primitive that removes caller-selected text from the trailing run of a table’s wrapper paragraph, never crossing a paragraph or table boundary, through the same open-safety finalize path.
Replacement: the
(N) short wordselection rule as an automation predicate passed to that primitive.Core surface affected:
hwpx.table_patch.strip_trailing_table_captions.
Sequence
Automation adds each replacement owner and switches its consumers. Core is unchanged and keeps answering old callers.
Core adds the neutral primitives (the heading-detector hook and the caller-selected trailing-text removal) in a minor release. The old names delegate to them with today’s rule, so their output does not change.
In the next major, every affected core name and behaviour emits a
DeprecationWarningthat names its automation replacement. Output does not change.In the major after it, the release that removes a core name also removes its allowlist or undetected entries and its group here. From then on the layer leak guard fails if the pattern comes back.
Every step keeps a core-only installation working for the generic features:
diff_paragraphs, document diff, and table and package preservation.
Regression tests for the plan input and caption removal — including text after
an ordinary table — come with the step that moves each group.
Compatibility — owner decision: option A
stable-api.md lets a stable name break only at a major
boundary, after a DeprecationWarning in an earlier major. The owner chose
option A for the names of the two remaining groups, which is the stable-name
policy as written (the two stable names of the moved reference group,
inspect_reference_consistency and REFERENCE_CONSISTENCY_REPORT_VERSION, went
with the 7.0 move and now raise an error that names their new place):
Release |
What the affected core names and behaviours do |
|---|---|
6.x |
Keep working without a warning. Automation replacements ship, and core may add the neutral primitives in a minor; the old names delegate to them with today’s rule. |
next major |
Emit a |
the major after it |
Removed, with their allowlist and undetected entries. Only the neutral primitives stay in core. |
“Affected” means everything listed under Core surface affected above: the
document-plan input of doc_diff and strip_trailing_table_captions.
The options that were weighed, for the record:
A. Keep every core name working through 6.x, warn in the next major, remove in the major after it. (chosen)
B. Warn from a 6.x minor once the automation replacements ship, remove in the next major. This needs an explicit exception to the stable-name policy for
inspect_reference_consistencyand the plan input ofdoc_diff.C. Never remove: freeze the core copies as compatibility code without feature work and keep their allowlist entries.
compatibility.decision in the JSON is A and compatibility.schedule holds
the table above. The contract test keeps the schedule relative: it rejects any
version number or date in the contract.