python-hwpx 3.0.0__tar.gz → 3.2.0__tar.gz

{python_hwpx-3.0.0/src/python_hwpx.egg-info → python_hwpx-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.0.0
+Version: 3.2.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>
@@ -64,15 +64,27 @@ Dynamic: license-file
 |---|---|---|
 | 📦 라이브러리 | **[`python-hwpx`](https://github.com/airmang/python-hwpx)** | 순수 파이썬 HWPX 파싱·편집·생성 코어 |
 | 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
-| 🎯 에이전트 스킬 | [`hwpx-skill`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 공식 온보딩 스킬 |
+| 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
+
+`python-hwpx`는 HWPX 파싱·편집·생성을 제공하는 코어 라이브러리이며,
+`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
+“first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
+
+현재 PyPI 공개 릴리스는 `python-hwpx 3.2.0`입니다. 일반
+`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
+현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
+성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
 
 ---
 
 ## 왜 python-hwpx인가
 
-- **한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
+- **코어 편집에 한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
 - **읽기부터 생성까지 한 코어** — 텍스트/서식 추출, 문단·표·양식 편집, 새 문서 생성, XSD 스키마 검증을 하나의 API로 처리합니다.
-- **에이전트·자동화 친화** — 같은 스택 위에서 `hwpx-mcp-server`와 공식 스킬이 직결됩니다.
+- **에이전트·자동화 친화** — 같은 프로젝트가 유지보수하는 `hwpx-mcp-server`와 `hwpx-plugin`이 코어에 연결됩니다.
+
+문서 파싱·편집·생성은 순수 Python으로 수행할 수 있습니다. 다만 페이지 나눔, 표 넘침,
+글꼴 대체 등 최종 시각 품질을 확언하려면 필요에 따라 실제 한컴 렌더 오라클을 별도로 사용합니다.
 
 ## 빠른 시작
 

{python_hwpx-3.0.0 → python_hwpx-3.2.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>
@@ -19,15 +19,27 @@
 |---|---|---|
 | 📦 라이브러리 | **[`python-hwpx`](https://github.com/airmang/python-hwpx)** | 순수 파이썬 HWPX 파싱·편집·생성 코어 |
 | 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
-| 🎯 에이전트 스킬 | [`hwpx-skill`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 공식 온보딩 스킬 |
+| 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
+
+`python-hwpx`는 HWPX 파싱·편집·생성을 제공하는 코어 라이브러리이며,
+`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
+“first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
+
+현재 PyPI 공개 릴리스는 `python-hwpx 3.2.0`입니다. 일반
+`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
+현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
+성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
 
 ---
 
 ## 왜 python-hwpx인가
 
-- **한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
+- **코어 편집에 한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
 - **읽기부터 생성까지 한 코어** — 텍스트/서식 추출, 문단·표·양식 편집, 새 문서 생성, XSD 스키마 검증을 하나의 API로 처리합니다.
-- **에이전트·자동화 친화** — 같은 스택 위에서 `hwpx-mcp-server`와 공식 스킬이 직결됩니다.
+- **에이전트·자동화 친화** — 같은 프로젝트가 유지보수하는 `hwpx-mcp-server`와 `hwpx-plugin`이 코어에 연결됩니다.
+
+문서 파싱·편집·생성은 순수 Python으로 수행할 수 있습니다. 다만 페이지 나눔, 표 넘침,
+글꼴 대체 등 최종 시각 품질을 확언하려면 필요에 따라 실제 한컴 렌더 오라클을 별도로 사용합니다.
 
 ## 빠른 시작
 

{python_hwpx-3.0.0 → python_hwpx-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.0.0"
+version = "3.2.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -109,11 +109,25 @@ python_version = "3.10"
 follow_imports = "skip"
 files = [
     "src/hwpx/document.py",
+    "src/hwpx/agent/commands.py",
+    "src/hwpx/agent/document.py",
+    "src/hwpx/agent/story.py",
+    "src/hwpx/oxml/_document_impl.py",
+    "src/hwpx/oxml/_document_primitives.py",
     "src/hwpx/oxml/document.py",
+    "src/hwpx/oxml/document_parts.py",
+    "src/hwpx/oxml/header_part.py",
+    "src/hwpx/oxml/memo.py",
+    "src/hwpx/oxml/numbering.py",
+    "src/hwpx/oxml/objects.py",
     "src/hwpx/opc/package.py",
     "src/hwpx/opc/relationships.py",
     "src/hwpx/oxml/paragraph.py",
     "src/hwpx/oxml/run.py",
+    "src/hwpx/oxml/section.py",
+    "src/hwpx/oxml/section_format.py",
+    "src/hwpx/oxml/section_story.py",
+    "src/hwpx/oxml/simple_parts.py",
     "src/hwpx/oxml/table.py",
     "src/hwpx/quality/policy.py",
     "src/hwpx/quality/report.py",
@@ -128,18 +142,30 @@ files = [
 ]
 ignore_missing_imports = true
 
-[[tool.mypy.overrides]]
-module = ["hwpx.document", "hwpx.oxml.document"]
-ignore_errors = true
-
 [tool.pyright]
-# Keep basic pyright focused on OPC/tooling modules that currently pass
-# without suppressing their real diagnostics.
+# Keep basic pyright focused on the explicit gradual scope. Feature 025 adds
+# both central facades and every extracted/touched runtime owner to the gate.
 include = [
+    "src/hwpx/document.py",
+    "src/hwpx/agent/commands.py",
+    "src/hwpx/agent/document.py",
+    "src/hwpx/agent/story.py",
+    "src/hwpx/oxml/_document_impl.py",
+    "src/hwpx/oxml/_document_primitives.py",
+    "src/hwpx/oxml/document.py",
+    "src/hwpx/oxml/document_parts.py",
+    "src/hwpx/oxml/header_part.py",
+    "src/hwpx/oxml/memo.py",
+    "src/hwpx/oxml/numbering.py",
+    "src/hwpx/oxml/objects.py",
     "src/hwpx/opc/package.py",
     "src/hwpx/opc/relationships.py",
     "src/hwpx/oxml/paragraph.py",
     "src/hwpx/oxml/run.py",
+    "src/hwpx/oxml/section.py",
+    "src/hwpx/oxml/section_format.py",
+    "src/hwpx/oxml/section_story.py",
+    "src/hwpx/oxml/simple_parts.py",
     "src/hwpx/oxml/table.py",
     "src/hwpx/quality/policy.py",
     "src/hwpx/quality/report.py",

{python_hwpx-3.0.0 → python_hwpx-3.2.0}/src/hwpx/agent/__init__.py

@@ -18,6 +18,20 @@ from .model import (
 from .catalog import agent_catalog, agent_json_schemas, catalog_hash, human_help, node_help
 from .commands import apply_document_commands
 from .document import HwpxAgentDocument, NodeRecord
+from .form_plan import (
+    MIXED_FORM_COMPILED_PLAN_SCHEMA,
+    MIXED_FORM_LOCATOR_KINDS,
+    MIXED_FORM_PLAN_SCHEMA,
+    MIXED_FORM_REQUEST_SCHEMA,
+    MixedFormPlan,
+    MixedFormResolution,
+    apply_mixed_form_fill,
+    apply_mixed_form_plan,
+    mixed_form_json_schemas,
+    plan_mixed_form_fill,
+    validate_mixed_form_plan,
+    validate_mixed_form_request,
+)
 from .path import PathSegment, SemanticPath, canonicalize_path, parse_path
 from .query import QueryResult, SemanticSelector, parse_selector
 from .blueprint import (
@@ -52,6 +66,10 @@ __all__ = [
     "AGENT_COMMAND_SCHEMA",
     "AGENT_ERROR_SCHEMA",
     "AGENT_NODE_SCHEMA",
+    "MIXED_FORM_COMPILED_PLAN_SCHEMA",
+    "MIXED_FORM_LOCATOR_KINDS",
+    "MIXED_FORM_PLAN_SCHEMA",
+    "MIXED_FORM_REQUEST_SCHEMA",
     "BLUEPRINT_CATALOG_SCHEMA",
     "BLUEPRINT_REPLAY_RESULT_SCHEMA",
     "BLUEPRINT_REPLAY_SCHEMA",
@@ -65,6 +83,8 @@ __all__ = [
     "BlueprintBundle",
     "BlueprintDumpResult",
     "HwpxAgentDocument",
+    "MixedFormPlan",
+    "MixedFormResolution",
     "NodeRecord",
     "PathSegment",
     "QueryResult",
@@ -74,6 +94,8 @@ __all__ = [
     "agent_json_schemas",
     "agent_contract_manifest",
     "apply_document_commands",
+    "apply_mixed_form_fill",
+    "apply_mixed_form_plan",
     "blueprint_catalog",
     "blueprint_catalog_hash",
     "blueprint_hash",
@@ -84,15 +106,19 @@ __all__ = [
     "canonicalize_path",
     "catalog_hash",
     "human_help",
+    "mixed_form_json_schemas",
     "node_help",
     "parse_path",
     "parse_selector",
+    "plan_mixed_form_fill",
     "dump_document_blueprint",
     "read_blueprint_bundle",
     "repack_blueprint_bundle",
     "replay_document_blueprint",
     "validate_agent_batch",
     "validate_agent_command",
+    "validate_mixed_form_plan",
+    "validate_mixed_form_request",
     "validate_blueprint_manifest",
     "validate_replay_request",
     "write_blueprint_bundle",

{python_hwpx-3.0.0 → python_hwpx-3.2.0}/src/hwpx/agent/catalog.py

@@ -9,10 +9,16 @@ from copy import deepcopy
 from typing import Any
 
 from .model import (
+    AGENT_BATCH_SCHEMA,
     AGENT_CATALOG_SCHEMA,
+    MAX_COMMANDS,
     AgentContractError,
     NODE_KINDS,
     NODE_PROPERTY_CATALOG_V1,
+    QUALITY_KEYS,
+    QUALITY_MODES,
+    REVISION_PATTERN,
+    VERIFICATION_REQUIREMENTS,
     agent_contract_manifest,
 )
 
@@ -78,6 +84,22 @@ def agent_json_schemas() -> dict[str, Any]:
                 "properties": {key: value for key, value in properties.items() if key in allowed},
             }
         )
+    quality_object = {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": {
+            "mode": {"enum": list(QUALITY_MODES)},
+            "renderCheck": {"enum": ["off", "auto", "required"]},
+            "xsdMode": {"enum": ["off", "lint"]},
+            "overflowPolicy": {"enum": ["fail", "warn", "truncate"]},
+            "layoutLint": {"enum": ["off", "warn", "strict"]},
+            "preserveUnmodifiedParts": {"type": "boolean"},
+            "requireReferenceIntegrity": {"type": "boolean"},
+        },
+    }
+    if set(quality_object["properties"]) != set(QUALITY_KEYS):  # pragma: no cover
+        raise AssertionError("quality JSON Schema drifted from QUALITY_KEYS")
+
     return {
         "node": {
             "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -113,6 +135,69 @@ def agent_json_schemas() -> dict[str, Any]:
             "title": "HwpxAgentCommand v1",
             "oneOf": command_variants,
         },
+        "batch": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": "HwpxAgentBatch v1",
+            "type": "object",
+            "required": [
+                "schemaVersion",
+                "input",
+                "output",
+                "commands",
+                "expectedRevision",
+                "idempotencyKey",
+                "dryRun",
+                "quality",
+                "verificationRequirements",
+            ],
+            "additionalProperties": False,
+            "properties": {
+                "schemaVersion": {"const": AGENT_BATCH_SCHEMA},
+                "input": {
+                    "type": "object",
+                    "required": ["filename"],
+                    "additionalProperties": False,
+                    "properties": {"filename": {"type": "string", "minLength": 1}},
+                },
+                "output": {
+                    "type": "object",
+                    "required": ["filename", "overwrite"],
+                    "additionalProperties": False,
+                    "properties": {
+                        "filename": {"type": "string", "minLength": 1},
+                        "overwrite": {"type": "boolean"},
+                    },
+                },
+                "commands": {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": MAX_COMMANDS,
+                    "items": {"oneOf": deepcopy(command_variants)},
+                },
+                "expectedRevision": {
+                    "type": ["string", "null"],
+                    "pattern": REVISION_PATTERN.pattern,
+                },
+                "idempotencyKey": {
+                    "type": ["string", "null"],
+                    "minLength": 1,
+                    "maxLength": 128,
+                },
+                "dryRun": {"type": "boolean"},
+                "quality": {
+                    "oneOf": [
+                        {"enum": list(QUALITY_MODES)},
+                        deepcopy(quality_object),
+                        {"type": "null"},
+                    ]
+                },
+                "verificationRequirements": {
+                    "type": "array",
+                    "items": {"enum": list(VERIFICATION_REQUIREMENTS)},
+                    "uniqueItems": True,
+                },
+            },
+        },
         "queryInput": {
             "$schema": "https://json-schema.org/draft/2020-12/schema",
             "type": "object",

{python_hwpx-3.0.0 → python_hwpx-3.2.0}/src/hwpx/agent/commands.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import Any
 from xml.etree import ElementTree as ET
 
-from lxml import etree as LET
+from lxml import etree as LET  # type: ignore[reportAttributeAccessIssue]  # lxml has no complete bundled typing
 
 from hwpx.document import HwpxDocument
 from hwpx.oxml import HwpxOxmlTable
@@ -38,6 +38,12 @@ from .model import (
     validate_agent_batch,
 )
 from .path import parse_path
+from .story import (
+    HEADER_STORY_EDITABLE_PROPERTIES,
+    HEADER_STORY_KIND,
+    HeaderStoryBinding,
+    try_parse_header_story_path,
+)
 
 _EMPTY_REVISION = "sha256:" + hashlib.sha256(b"").hexdigest()
 _HWP_UNITS_PER_MM = 7200 / 25.4
@@ -242,6 +248,21 @@ def _validate_property_values(kind: str, properties: Mapping[str, Any], *, creat
             raise AgentContractError("unknown_property", f"untyped property: {target}", target=target)
 
 
+def _validate_header_story_properties(properties: Mapping[str, Any]) -> None:
+    unknown = sorted(set(properties) - HEADER_STORY_EDITABLE_PROPERTIES)
+    if unknown:
+        raise AgentContractError(
+            "unknown_property",
+            f"header does not support properties: {unknown}",
+            target=f"header.{unknown[0]}",
+        )
+    if "text" not in properties:
+        raise AgentContractError(
+            "invalid_syntax", "existing header set requires text", target="header.text"
+        )
+    _require_string(properties["text"], "header.text")
+
+
 def _preflight(batch: Mapping[str, Any]) -> None:
     """Reject the complete static command matrix before the first mutation."""
 
@@ -254,6 +275,9 @@ def _preflight(batch: Mapping[str, Any]) -> None:
                 return alias_kinds[command_id][field]
             except KeyError as exc:  # validate_agent_batch already checks ordering
                 raise AgentContractError("not_found", f"unknown command alias: {value}") from exc
+        story = try_parse_header_story_path(value)
+        if story is not None:
+            return story.kind
         parsed = parse_path(value)
         return parsed.segments[-1].kind if parsed.segments else "document"
 
@@ -264,6 +288,9 @@ def _preflight(batch: Mapping[str, Any]) -> None:
                 return alias_kinds[command_id]["parentPath" if field == "path" else field]
             except KeyError:
                 return "document"
+        story = try_parse_header_story_path(value)
+        if story is not None:
+            return "section"
         parsed = parse_path(value)
         return parsed.segments[-2].kind if len(parsed.segments) > 1 else "document"
 
@@ -298,6 +325,19 @@ def _preflight(batch: Mapping[str, Any]) -> None:
             }
             continue
         source_kind = reference_kind(command["path"])
+        if source_kind == HEADER_STORY_KIND:
+            if op != "set":
+                raise AgentContractError(
+                    "unsupported_operation",
+                    f"{op} is unsupported for {source_kind}",
+                    target=command["commandId"],
+                )
+            _validate_header_story_properties(command["properties"])
+            alias_kinds[command["commandId"]] = {
+                "path": source_kind,
+                "parentPath": "section",
+            }
+            continue
         if op not in NODE_PROPERTY_CATALOG_V1[source_kind]["operations"]:
             raise AgentContractError(
                 "unsupported_operation",
@@ -309,11 +349,11 @@ def _preflight(batch: Mapping[str, Any]) -> None:
         destination_kind = parent_kind(command["path"])
         if op in {"move", "copy"}:
             destination_kind = reference_kind(command["parent"])
-            expected_parent = _MOVE_COPY_PARENTS.get(source_kind)
-            if destination_kind != expected_parent:
+            move_parent = _MOVE_COPY_PARENTS.get(source_kind)
+            if destination_kind != move_parent:
                 raise AgentContractError(
                     "incompatible_parent",
-                    f"{source_kind} requires a {expected_parent} parent, not {destination_kind}",
+                    f"{source_kind} requires a {move_parent} parent, not {destination_kind}",
                     target=command["commandId"],
                 )
         alias_kinds[command["commandId"]] = {
@@ -570,6 +610,42 @@ def _mark_containing_section(document: HwpxDocument, target: Any) -> None:
     raise AgentContractError("not_found", "mutated element is detached")
 
 
+def _apply_header_story_set(
+    binding: HeaderStoryBinding, properties: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Apply the bounded existing-header mutation through its OXML owner."""
+
+    _validate_header_story_properties(properties)
+    try:
+        binding.native.set_simple_text_preserving(properties["text"])
+    except AgentContractError:
+        raise
+    except ValueError as exc:
+        # The OXML owner uses ValueError for rich/control-bearing or otherwise
+        # structurally unsafe headers.  Do not let it degrade to the generic
+        # invariant envelope or fall back to the destructive whole-story setter.
+        message = str(exc) or "header content cannot be edited losslessly"
+        lowered = message.lower()
+        code = (
+            "ambiguous_target"
+            if "ambiguous" in lowered
+            else "not_found"
+            if "not found" in lowered
+            else "unsupported_content"
+        )
+        raise AgentContractError(
+            code,
+            message,
+            target=binding.path,
+        ) from exc
+    return {
+        "text": {
+            "before": binding.text,
+            "after": properties["text"],
+        }
+    }
+
+
 def _apply_set(document: HwpxDocument, record: NodeRecord, properties: Mapping[str, Any]) -> dict[str, Any]:
     _ensure_operation(record, "set")
     _validate_property_values(record.kind, properties, creating=False)
@@ -711,7 +787,10 @@ def _add(
         if "pageHeightMm" in properties:
             size_kwargs["height"] = round(properties["pageHeightMm"] * _HWP_UNITS_PER_MM)
         if size_kwargs:
-            created.properties.set_page_size(**size_kwargs)
+            created.properties.set_page_size(
+                width=size_kwargs.get("width"),
+                height=size_kwargs.get("height"),
+            )
         return created
     if kind == "paragraph":
         created = parent.native.add_paragraph(str(properties.get("text", "")))
@@ -1081,6 +1160,47 @@ def _member_diff(before: bytes, after: bytes) -> dict[str, Any]:
         return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
 
 
+def _verify_header_story_candidates(
+    candidate_data: bytes,
+    candidate_revision: str,
+    expectations: Mapping[str, Mapping[str, str]],
+) -> dict[str, Any]:
+    receipts: list[dict[str, Any]] = []
+    if expectations:
+        with HwpxDocument.open(candidate_data) as reopened:
+            view = HwpxAgentDocument.from_document(
+                reopened, revision=candidate_revision
+            )
+            for expectation in expectations.values():
+                path = expectation["path"]
+                binding = view._resolve_header_story(path)
+                if (
+                    binding.stable_id != expectation["stableId"]
+                    or binding.page_type != expectation["pageType"]
+                    or binding.text != expectation["text"]
+                ):
+                    raise AgentContractError(
+                        "verification_failed",
+                        "reopened header story does not match the committed binding",
+                        target=path,
+                    )
+                receipts.append(
+                    {
+                        "commandId": expectation["commandId"],
+                        "path": binding.path,
+                        "stableId": binding.stable_id,
+                        "pageType": binding.page_type,
+                        "textMatched": True,
+                    }
+                )
+    return {
+        "schemaVersion": "hwpx.agent-story-preservation/v1",
+        "ok": True,
+        "storyCount": len(receipts),
+        "stories": receipts,
+    }
+
+
 def _request_hash(batch: Mapping[str, Any]) -> str:
     payload = json.dumps(
         batch,
@@ -1192,6 +1312,7 @@ def apply_document_commands(
         aliases: dict[str, dict[str, str]] = {}
         identity_changes: list[Mapping[str, str]] = []
         semantic_changes: list[Mapping[str, Any]] = []
+        story_expectations: dict[str, Mapping[str, str]] = {}
         _call_fault(fault_injector, "before_open")
         with HwpxDocument.open(input_data) as document:
             view = HwpxAgentDocument.from_document(document, revision=input_revision)
@@ -1203,11 +1324,24 @@ def apply_document_commands(
                 parent_path: str | None = None
                 changed: dict[str, Any] = {}
                 generated: list[dict[str, str]] = []
+                target_native: Any | None = None
+                story_before: HeaderStoryBinding | None = None
                 if op == "set":
                     resolved_path = _resolve_alias(command["path"], aliases)
-                    record = view.resolve_record(resolved_path, expected_revision=input_revision)
-                    changed = _apply_set(document, record, command["properties"])
-                    target_native = record.native
+                    story_path = try_parse_header_story_path(resolved_path)
+                    if story_path is not None:
+                        story_before = view._resolve_header_story(
+                            story_path, expected_revision=input_revision
+                        )
+                        changed = _apply_header_story_set(
+                            story_before, command["properties"]
+                        )
+                    else:
+                        record = view.resolve_record(
+                            resolved_path, expected_revision=input_revision
+                        )
+                        changed = _apply_set(document, record, command["properties"])
+                        target_native = record.native
                 elif op == "add":
                     parent_path = _resolve_alias(command["parent"], aliases)
                     parent = view.resolve_record(parent_path, expected_revision=input_revision)
@@ -1244,7 +1378,26 @@ def apply_document_commands(
 
                 _call_fault(fault_injector, "after_command", index)
                 view = HwpxAgentDocument.from_document(document, revision=input_revision)
-                if op == "set" and resolved_path is not None:
+                result_stable_id: str | None = None
+                if story_before is not None and resolved_path is not None:
+                    target_story = view._resolve_header_story(resolved_path)
+                    if target_story.stable_id != story_before.stable_id:
+                        raise AgentContractError(
+                            "invariant_violation",
+                            "header story identity changed during text edit",
+                            target=resolved_path,
+                        )
+                    result_path = target_story.path
+                    result_parent = target_story.parent_path
+                    result_stable_id = target_story.stable_id
+                    story_expectations[target_story.binding_key] = {
+                        "commandId": command_id,
+                        "path": target_story.path,
+                        "stableId": target_story.stable_id,
+                        "pageType": target_story.page_type,
+                        "text": command["properties"]["text"],
+                    }
+                elif op == "set" and resolved_path is not None:
                     # Some native bindings (notably form fields) are request-local
                     # match dictionaries.  A property edit is non-structural, so
                     # its canonical path is the durable post-edit lookup key.
@@ -1269,6 +1422,11 @@ def apply_document_commands(
                     "generatedIdentities": generated,
                     "warnings": [],
                 }
+                if result_stable_id is not None:
+                    # Command results are already an untyped JSON mapping.  This
+                    # story-only receipt carries the actual stable identity
+                    # without changing AgentBatchResult or the ToolSpec schema.
+                    result["stableId"] = result_stable_id
                 command_results.append(result)
                 semantic_changes.append(
                     {
@@ -1285,6 +1443,12 @@ def apply_document_commands(
             _call_fault(fault_injector, "after_serialize")
 
             candidate_revision = _revision(candidate_data)
+            if story_expectations:
+                verification["storyPreservation"] = _verify_header_story_candidates(
+                    candidate_data,
+                    candidate_revision,
+                    story_expectations,
+                )
             semantic_diff = {
                 "schemaVersion": "hwpx.agent-semantic-diff/v1",
                 "inputRevision": input_revision,