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

{python_hwpx-3.1.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.1.0
+Version: 3.2.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -70,7 +70,8 @@ Dynamic: license-file
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 공개 릴리스와 최소 호환 코어 버전은 모두 `python-hwpx 3.1.0`입니다.
+현재 PyPI 공개 릴리스는 `python-hwpx 3.2.0`입니다. 일반
+`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
 

{python_hwpx-3.1.0 → python_hwpx-3.2.0}/README.md

@@ -25,7 +25,8 @@
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 공개 릴리스와 최소 호환 코어 버전은 모두 `python-hwpx 3.1.0`입니다.
+현재 PyPI 공개 릴리스는 `python-hwpx 3.2.0`입니다. 일반
+`pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.1.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.1.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,

{python_hwpx-3.1.0 → python_hwpx-3.2.0}/src/hwpx/agent/document.py

@@ -8,7 +8,7 @@ from collections import Counter, defaultdict
 from dataclasses import dataclass, field
 from os import PathLike
 from pathlib import Path
-from typing import Any
+from typing import Any, Sequence, cast
 
 from hwpx.document import HwpxDocument
 from hwpx.oxml import HwpxOxmlShape
@@ -22,7 +22,14 @@ from .model import (
     NODE_PROPERTY_CATALOG_V1,
 )
 from .path import SemanticPath, canonicalize_path, identified_segment, indexed_segment
+from .query import QueryRecord as _QueryRecord
 from .query import QueryResult, evaluate_selector, parse_selector
+from .story import (
+    HeaderStoryBinding,
+    HeaderStoryPath,
+    parse_header_story_path,
+    resolve_header_story,
+)
 
 _HWP_UNITS_PER_MM = 7200 / 25.4
 _SHAPE_KINDS = frozenset({"line", "rect", "ellipse", "arc", "polygon", "curve", "connectLine"})
@@ -129,7 +136,7 @@ class HwpxAgentDocument:
     def __enter__(self) -> "HwpxAgentDocument":
         return self
 
-    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:  # type: ignore[exit-return]  # frozen public signature
         self.close()
         return False
 
@@ -689,6 +696,25 @@ class HwpxAgentDocument:
             raise AgentContractError("volatile_target", "target has a positional path", target=canonical)
         return record
 
+    def _resolve_header_story(
+        self,
+        path: str | HeaderStoryPath,
+        *,
+        expected_revision: str | None = None,
+    ) -> HeaderStoryBinding:
+        """Resolve the private command-only existing-header seam.
+
+        Header stories deliberately remain absent from ``records``, ``get``,
+        and ``query`` so the frozen public projection/catalog does not drift.
+        """
+
+        parsed = parse_header_story_path(path) if isinstance(path, str) else path
+        if expected_revision is not None and expected_revision != self.revision:
+            raise AgentContractError(
+                "stale_revision", "document revision does not match", target=parsed.canonical
+            )
+        return resolve_header_story(self.document, parsed)
+
     def _public_node(self, record: NodeRecord, *, depth: int, child_limit: int) -> AgentNode:
         supported_total = len(record.child_paths)
         selected_paths = record.child_paths[:child_limit] if depth > 0 else []
@@ -751,7 +777,8 @@ class HwpxAgentDocument:
         if expected_revision is not None and expected_revision != self.revision:
             raise AgentContractError("stale_revision", "document revision does not match", target="selector")
         parsed = parse_selector(selector)
-        matches, truncated = evaluate_selector(self.records, parsed, limit=limit)
+        query_records = cast(Sequence[_QueryRecord], self.records)
+        matches, truncated = evaluate_selector(query_records, parsed, limit=limit)
         if not 0 <= node_depth <= MAX_VIEW_DEPTH:
             raise AgentContractError("resource_limit", "nodeDepth is out of bounds", target="nodeDepth")
         if not 1 <= child_limit <= MAX_CHILDREN_PER_NODE:
@@ -760,7 +787,12 @@ class HwpxAgentDocument:
             selector=selector,
             revision=self.revision,
             nodes=tuple(
-                self._public_node(record, depth=node_depth, child_limit=child_limit) for record in matches
+                self._public_node(
+                    cast(NodeRecord, record),
+                    depth=node_depth,
+                    child_limit=child_limit,
+                )
+                for record in matches
             ),
             truncated=truncated,
         )

python_hwpx-3.2.0/src/hwpx/agent/story.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Private, contract-neutral bindings for existing non-body stories.
+
+The public semantic path grammar intentionally remains frozen at the Feature
+024 catalog.  This module recognizes one narrower command-only seam: an
+existing section header selected by its native id or page type.  It does not
+project headers into the public view, accept package paths, or expose XML.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from .model import AgentContractError
+from .path import MAX_PATH_CHARS
+
+HEADER_STORY_KIND = "header"
+HEADER_STORY_EDITABLE_PROPERTIES = frozenset({"text"})
+HEADER_PAGE_TYPES = frozenset({"BOTH", "EVEN", "ODD"})
+
+_HEADER_STORY_RE = re.compile(
+    r"^/section\[(?P<section>0*[1-9][0-9]*)\]/header\["
+    r"@(?P<attribute>id|page-type)=(?P<value>\"(?:[^\"\\]|\\.)*\")\]$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class HeaderStoryPath:
+    """Parsed command-only path for one existing section header."""
+
+    section_index: int
+    attribute: str
+    value: str
+
+    @property
+    def kind(self) -> str:
+        return HEADER_STORY_KIND
+
+    @property
+    def canonical(self) -> str:
+        value = json.dumps(self.value, ensure_ascii=False, separators=(",", ":"))
+        return (
+            f"/section[{self.section_index}]/"
+            f"header[@{self.attribute}={value}]"
+        )
+
+    @property
+    def parent_path(self) -> str:
+        return f"/section[{self.section_index}]"
+
+
+@dataclass(frozen=True, slots=True)
+class HeaderStoryBinding:
+    """Request-local native binding for an existing logical header."""
+
+    path: str
+    parent_path: str
+    stable_id: str
+    native_id: str
+    page_type: str
+    section_index: int
+    native: Any
+    text: str
+
+    @property
+    def kind(self) -> str:
+        return HEADER_STORY_KIND
+
+    @property
+    def binding_key(self) -> str:
+        # Native ids are not promised to be document-global.  Section scope is
+        # part of the logical binding even though the receipt exposes the same
+        # kind:id stable-id convention used by projected semantic nodes.
+        return f"{self.section_index}:{self.native_id}"
+
+
+def try_parse_header_story_path(value: object) -> HeaderStoryPath | None:
+    """Return a private header path, or ``None`` for the public path parser.
+
+    Only exact supported forms are intercepted.  Unsupported forms such as
+    ``header[1]`` deliberately continue through :func:`parse_path` and retain
+    the frozen ``unknown_kind`` behavior.
+    """
+
+    if not isinstance(value, str) or "/header[@" not in value:
+        return None
+    if len(value) > MAX_PATH_CHARS:
+        raise AgentContractError("resource_limit", "path is too long", target="path")
+    match = _HEADER_STORY_RE.fullmatch(value)
+    if match is None:
+        return None
+    try:
+        decoded = json.loads(match.group("value"))
+    except (TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise AgentContractError(
+            "invalid_syntax", "invalid header story path string", target="path"
+        ) from exc
+    if not isinstance(decoded, str) or not decoded or len(decoded) > 256:
+        raise AgentContractError(
+            "resource_limit", "header story selector is invalid", target="path"
+        )
+    attribute = match.group("attribute")
+    if attribute == "page-type" and decoded not in HEADER_PAGE_TYPES:
+        raise AgentContractError(
+            "invalid_syntax",
+            "header page type must be BOTH, EVEN, or ODD",
+            target="path",
+        )
+    return HeaderStoryPath(
+        section_index=int(match.group("section")),
+        attribute=attribute,
+        value=decoded,
+    )
+
+
+def parse_header_story_path(value: str) -> HeaderStoryPath:
+    """Parse an exact private header path for focused internal tests."""
+
+    parsed = try_parse_header_story_path(value)
+    if parsed is None:
+        raise AgentContractError(
+            "invalid_syntax", "unsupported header story path", target="path"
+        )
+    return parsed
+
+
+def resolve_header_story(document: Any, path: HeaderStoryPath) -> HeaderStoryBinding:
+    """Resolve one unique direct logical header without scanning descendants."""
+
+    try:
+        sections = document.sections
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "document section structure is unavailable", target=path.canonical
+        ) from exc
+    if path.section_index > len(sections):
+        raise AgentContractError(
+            "not_found", "header story section does not exist", target=path.canonical
+        )
+    section = sections[path.section_index - 1]
+    try:
+        headers = tuple(section.properties.headers)
+        if path.attribute == "id":
+            matches = [header for header in headers if header.id == path.value]
+        else:
+            matches = [
+                header for header in headers if header.apply_page_type == path.value
+            ]
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "section header structure is invalid", target=path.canonical
+        ) from exc
+
+    if not matches:
+        raise AgentContractError(
+            "not_found", f"existing header story not found: {path.canonical}", target=path.canonical
+        )
+    if len(matches) > 1:
+        raise AgentContractError(
+            "ambiguous_target",
+            f"header story selector is not unique: {path.canonical}",
+            target=path.canonical,
+        )
+
+    header = matches[0]
+    try:
+        native_id = header.id
+        page_type = header.apply_page_type
+        text = header.text
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "header story cannot be read safely", target=path.canonical
+        ) from exc
+    if not native_id or len(native_id) > 256:
+        raise AgentContractError(
+            "unsupported_content", "header story has no bounded native identity", target=path.canonical
+        )
+    if page_type not in HEADER_PAGE_TYPES:
+        raise AgentContractError(
+            "unsupported_content", "header story has an unsupported page type", target=path.canonical
+        )
+
+    return HeaderStoryBinding(
+        path=path.canonical,
+        parent_path=path.parent_path,
+        stable_id=f"header:{native_id}",
+        native_id=native_id,
+        page_type=page_type,
+        section_index=path.section_index,
+        native=header,
+        text=text,
+    )
+
+
+__all__ = [
+    "HEADER_PAGE_TYPES",
+    "HEADER_STORY_EDITABLE_PROPERTIES",
+    "HEADER_STORY_KIND",
+    "HeaderStoryBinding",
+    "HeaderStoryPath",
+    "parse_header_story_path",
+    "resolve_header_story",
+    "try_parse_header_story_path",
+]