python-hwpx 3.0.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

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",

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",

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,

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,
         )